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About This Guide 

The AT&T 3270 Emulator+ provides interactive data communication 
between ASCII terminals at an AT&T 3B Computer and remote mainframe 
systems (IBM or other). It provides the following functional features: 

■ IBM 3270 emulation 

■ Support for both the Binary Synchronous Communications (BSC) and 
the Systems Network Architecture (SNA) Synchronous Data Link 
Control (SDLC) protocols 

■ The ability to run the AT&T SNA/RJE Emulator+ simultaneously 
over the same SDLC link to the remote host computer 

o The 3270 High Level Language Application Program Interface 
(HLLAPI) 

■ The 3270 Application Program Interface (API) 

o The AT&T 3270 Emulator+ ESCORT Interface 

This guide provides the information that you will need to use the AT&T 
3270 Emulator+ High Level Language Application Program Interface 
(HLLAPI) or the AT&T 3270 EmulatorH- Application Program Interface 
(API). 



Who Should Read This Guide 

This guide is intended for AT&T 3B Computer users and programmers 
who want to write C language application programs that use the functions 
of the AT&T 3270 Emulator+ HLLAPI and of the AT&T 3270 Emulator+ 
API. 

The AT&T 3270 Emulator+ HLLAPI is a library of C language functions 
that can be called from a C language application program to communicate a 
series of 3270 tasks to a remote host computer (IBM or other). The AT&T 
3270 Emulator+ API is a low-level version of the AT&T 3270 Emulator+ 
HLLAPI that provides two modes of accessing a remote host: 3270 data 
stream mode and "raw" data stream mode. 
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In 3270 data stream mode, an application program using either HLLAPI 
or API functions to communicate with the remote system is functionally 
equivalent to the interactive user interface to the host through a 3278/9 ter- 
minal. The raw mode, only available in the API, provides a raw data 
transfer interface that is independent of any terminal functionality (i.e., no 
3270 data stream encoding /decoding is done). 

In general, the AT&T 3270 Emulator+ API is more difficult to learn and 
use than the AT&T 3270 Emulators- HLLAPI. Therefore, the use of HLLAPI 
rather than API functions is recommended, except in those application pro- 
grams that must access the remote host computer in raw data stream mode. 



Organization of This Guide 

The HLLAPI Programmer's Guide is organized as follows: 

■ The Preface discusses prerequisites for the understanding and use of 
the AT&T 3270 Emulator+ application programming facilities. 

■ Chapter 1, HLLAPI and API, presents an overview of the AT&T 3270 
Emulator+ application programming facilities, HLLAPI and API. 

■ Chapter 2, HLLAPI Overview, introduces AT&T HLLAPI concepts, and 
discusses several important things that you should know before get- 
ting started. 

■ Chapter 3, HLLAPI Tutorial, explains the on-line tutorial program for 
the AT&T 3270 Emulator+ HLLAPI. 

■ Chapter 4, Application Program Interface, discusses application program 
development using the AT&T 3270 Emulator+ API. 

■ Manual Pages contains the manual pages for the HLLAPI and API 
function calls. 

■ Appendix A, AT&T 3270 Emulator+ HLLAPI Examples, provides exam- 
ples of how you would code a C language application program using 
AT&T HLLAPI function calls. 

■ Appendix B, AT&T 3270 Emulator+ HLLAPI Functions, lists the sup- 
ported and unsupported IBM HLLAPI functions and the AT&T 3270 
Emulator+ HLLAPI extensions. 
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■ Appendix C, The xhllapi.h File, shows the xhllapi.h header file that 
you must include in your application program. 

■ Appendix D, File Transfer Messages, explains the messages that you 
may see when transferring files between an AT&T 3B Computer and 
a remote host computer. 

■ Appendix E, API Program Check Error Codes, lists the error messages 
that you may get when an API system call fails because of errors in 
the data received from the remote host computer. 

■ Appendix F, API Communication Check Error Codes, lists the error mes- 
sages that you may get when an API system call fails because of con- 
ditions detected at the local communications interface. 

■ Appendix G, API User/ System Error Codes, lists the error messages that 
you may get when an API system call fails because of user applica- 
tion or system errors. 

■ Appendix H, API LUVJTRC Status Displays, explains the API trace 
display that appears in the status line. 

B Appendix I, API External Symbols, lists the global symbols used by the 
API library. 

■ The Glossary defines important terms that are used in this guide. 

■ The Index lists the key subjects treated in this guide and gives page 
references for them. 
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Operating Requirements 



AT&T 3B Computer 

The AT&T 3270 Emulator+ HLLAPI and API are intended for use on an 
AT&T 3B Computer. 

■ The 3B2 Computer must be equipped with a minimum of two mega- 
bytes of memory and an Intelligent Serial Controller (ISC) board. 
The ISC board should be installed following the procedures in the 
AT&T 3B2 Computer Intelligent Serial Controller Manual. (A separate ISC 
board is required for each active communication line to a host.) Each 
board supports a single line of either BSC or SNA/SDLC protocol, A 
user can install multiple ISC boards in the computer with any desired 
mix of boards supporting BSC or SNA. 

■ The 3B5 and 3B15 Computers must be equipped with an 

Input/ Output Accelerator (lOA) processor and a Synchronous Data 
Link (SDLI). 

■ The 3B4000 Computer requires an ACP with an associated ISC card. 

The AT&T 3270 EmulatorH- supports up to 9600 baud for BSC and up to 
19.2 kilobaud for SNA/SDLC operation. 

The 3B Computer connects to the host using the switched telephone 
network or a non-switched (leased or private) line and a synchronous 
modem. The modem must supply clock to the ISC board. The host con- 
nects to the communication line through a communications controller, data 
adapter unit, or transmission control unit that is attached to the line using a 
modem that is compatible with the modem used by the 3B Computer. 



Terminal Requirements 

The AT&T 3270 Emulator^- provides screen and keyboard customization 
functions to allow work with any ASCII terminal supported by the AT&T 
3B Computer. In addition, pre-customized files are provided for the follow- 
ing terminals: 
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■ AT&T 4410, 4418, 4425, 605, 610, 615, 620, and 630 

■ Teletype 5410, 5418, and 5425 

■ Hewlett-Packard 2621 

■ Lear-Siegler ADM-3a 

■ Televideo 910, 924 

■ DECVT-100 

■ Tektronix 4105A 



Printer Requirements 

The printer emulation procedures require the following operating 
features: 

■ A RETURN is required to advance the print head to column 1 of the 
next line. 

■ A Line Feed (LF) is required to advance the print head position to 
the current column of the next line. On some printers you may use 
"stty" on the target device to execute a line feed. 

■ Backspace capability. 

■ Formfeed capability. 



Software Requirements 

The AT&T 3270 Emulator+ operates under UNIX System V Releases 2.0 
and later. Inter-Process Communication (IPC) software and the Terminal 
Information Utilities package must also be part of the software on your 3B 
Computer. 
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You must write your HLLAPI application program in the C program- 
ming language. This guide assumes that you are familiar with the UNIX 
System and the C programming language, although relevant information is 
included where needed. If you need additional information/ consult the 
following documents for the UNIX System V release running on your sys- 
tem: 

■ AT&T UNIX System V User's Guide 

■ AT&T UNIX System V User's Reference Manual 

■ AT&T UNIX System V Programmer's Guide 

■ AT&T UNIX System V Programmer's Reference Manual 
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Related Documentation 



This guide assumes that you have a working knowledge of the IBM 
3270 Personal Computer and the BSC and SNA/SDLC protocols. If you 
need additional information regarding these topics, you may refer to the 
following documents: 

■ IBM 3270 Personal Computer Control Program User's Guide and Reference 

■ IBM 3270 Personal Computer Control Program Programming Guide 

■ IBM 3270 Information Display System 

■ 3274 Control Unit Description and Programmer's Guide 

■ IBM Systems Network Architecture: Concepts and Products 

■ IBM Systems Network Archtecture Technical Overview 

■ IBM Synchronous Data Link Control (SDLC) Concepts 

■ IBM General Information: Binary Synchronous Communications 
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other AT&T 3270 Emulator+ Documentation 

For more information regarding the AT&T 3270 Emulator+ product, 
please refer to the following documents: 

■ AT&T 3270 Emulator^ Product Overview 

■ AT&T 3270 Emulator^ User's Guide 

■ AT&T 3270 Emulator+ System Administrator's Guide 

■ AT&T 3270 Emulator^ 3B2 Release Notes 

■ AT&T 3270 Emulator^ 385/15/4000 Release Notes 
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Introduction 



The AT&T 3270 Emulator+ includes two interfaces that allow the user's 
C language application programs to communicate a series of 3270 tasks to a 
remote host computer. These interfaces are the High Level Language 
Application Program Interface (HLLAPI), and the Application Program 
Interface (API). Both interfaces are libraries of C language functions that 
you can call from a C language application program to do a variety of func- 
tions. The AT&T 3270 Emulator-t- HLLAPI is a high-level extension of the 
AT&T 3270 Emulator+ API that is easier to learn and use. 



NOTE 



Although the AT&T 3270 Emulator+ HLLAPI is an extension of the 
AT&T 3270 Emulator+ API, their use is mutually exclusive. You can- 
not make function calls to both interfaces from the same application 
program. 



Both inexperienced and experienced users can increase their produc- 
tivity by using either interface in their application programs. Both inter- 
faces can: 

■ save users from writing complicated application programs to produce 
complex screens and commands 

■ automate logon sequences 

■ simplify complex 3270 tasks, such as copying and file transfers 

■ simplify existing remote host computer applications 

■ monitor 3270 tasks, such as console operation, response time control, 
and availability, without human intervention 

■ create remote host and workstation processing applications that 
divide the functions of an application between the host and the 
AT&T 3B Computer 

The AT&T 3270 Emulator+ HLLAPI provides the following additional 
advantages: 

■ Because it is an extension to the AT&T Emulator+ API, HLLAPI 
allows less experienced programmers to gain access to advanced 
AT&T 3270 Emulators- API functions. 
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■ Application programs that use AT&T 3270 Emulator+ HLLAPI func- 
tions are often shorter and easier to read and debug than those using 
API functions. 

■ The nature of the AT&T Emulator+ HLLAPI and the C programming 
language make structured programming techniques easy to imple- 
ment. 

■ Application programs that use AT&T 3270 Emulator+ HLLAPI func- 
tions are comparatively easy to maintain. 
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The High Level Language Application Program 
Interface (HLLAPI) 

The AT&T 3270 Emulator+ HLLAPI is largely compatible with the IBM 
3270 Personal Computer HLLAPI and provides extensions not available in 
the IBM product. The supported and unsupported IBM HLLAPI functions 
and the AT&T 3270 Emulator+ HLLAPI extensions are listed in Appendix B, 
HLLAPI Functions. 

A C language application program that uses the AT&T 3270 Emulator+ 
HLLAPI is capable of performing 3270 tasks without human intervention. 
The next section illustrates some situations in which your application pro- 
gram can use HLLAPI functions. 



AT&T 3270 Emulator+ HLLAPI Sample Scenarios 

The scenarios presented in this section illustrate HLLAPI functions that 
your application program can perform in these areas: 

■ analyzing, extracting, and using remote host computer messages 

■ sending keystrokes to a remote host computer from an AT&T 3B 
Computer 

■ distributed processing: intercepting communications between the 
remote host computer and the terminal user 

■ distributed processing: extracting data from host sessions 

■ distributed processing: transferring files to and from a remote host 
computer 

■ automating keystrokes 

■ filtering keystrokes 

Analyzing, Extracting, and Using Remote Host Computer Messages 

A terminal operator trying to start a transaction with a remote host com- 
puter normally follows these steps: 

1 . start the transaction 
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2. wait for a response from the host 

3 . analyze the response to find out if it is the expected one 

4 . extract and use the data from the response 

You can emulate these steps by using a series of AT&T Emulator^- HLLAPI 
functions. After determining the correct starting point for the host transac- 
tion, your application program can call the h_search (Search Presentation 
Space) HLLAPI function to determine which keyword messages or prompt- 
ing messages are on the display screen. 

Then your application program can use the hjsendkey (Send Key) 
HLLAPI function to key data into the remote host session and enter a host 
transaction. Your application program can also use the h_copypss (Copy 
Presentation Space to String) HLLAPI function (or any of several other 
Copy functions) to copy the desired data from the remote host into a 
specified data area. 

Some host systems do not stay locked in XCLOCK or XSYSTEM mode 
until they respond; instead, they quickly unlock the keyboard and allow 
the operator to stack other requests. In these situations, the terminal opera- 
tor depends on some other visual prompt to know that the data has 
returned, hjsearch (Search Presentation Space) allows your application pro- 
gram to search the presentation space while waiting. If no host event 
occurs after a reasonable timeout period, then your HLLAPI program can 
call a customized error message function. 



NOTE 



Your application program must be revised for even minor changes in the 
display messages. Subtle changes in display message syntax can make 
your program call a customized error message function erroneously. 



Sending Keystrokes to a Remote Host Computer 

If you want to write application programs that send keystrokes to a 
remote host computer, you should be aware of several things. Some appli- 
cation environments may only require that the terminal operator key in a 
string followed by the ENTER key to issue a command. Other applications 
may involve more complex 3270 formatted screens in which the terminal 
operator can enter data into any one of several fields. You must understand 
the fields that the display needs to have filled in. 
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You must be aware of the field lengths and contents when you are 
sending keystrokes to a field using hjsendkey (Send Key). If you fill in the 
field completely and the next attribute byte is an "autoskip/' the cursor will 
be moved to the next field. If you then enter a tab, you will skip to yet 
another field. 

On the other hand, if your keystrokes do not fill the field completely, 
there may be data left from prior input. (You can clear this data using the 
Erase End of Field (EOF) key.) 

Distributed Processing: intercepting Communications between tlie 
Host and ttie Terminal User 

There are a number of applications that provide a single end user inter- 
face, but perform their processing at two or more different locations. A 
HLLAPI application program can interact with host applications by inter- 
cepting the communications between the remote host computer and the ter- 
minal user. This can be done by having the application program ask to be 
notified each time the host presentation space is updated or every time the 
terminal user enters an AID key. 

Your application program can then use the HLLAPI Copy functions to 
update fields or presentation spaces, or send keystrokes to the host using 
the h_sendkey (Send Key) function. 

Distributed Processing: Extracting Data from Host Sessions 

Your application can take the following steps to extract host data for 
local use: 

1 . Your program must call the hjconnect (Connect Presentation Space) 
HLLAPI function to connect to the host presentation space contain- 
ing the data that will be copied. 

2. Your program can call the hjcopy (Copy Presentation Space to 
String) HLLAPI function to obtain the desired data from the host 
presentation space. 

3. Your program can then call the hjconnect (Connect Presentation 
Space) HLLAPI function to connect to a different presentation space 
where the data will be entered. 

4. Next, your program can use the hjsendkey (Send Key) HLLAPI 
function to route the data to that presentation space. 
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5. Finally, your program can use the h_sendkey Send Key) HLLAPI 
function to send the keystrokes that will start the application. 

You can also send data from your local application to the remote host com- 
puter. 

Distributed Processing: Transferring Files to and from a Remote 
Host Computer 

Your application program can use the h_send (Send File) and h_recv 
(Receive File) HLLAPI functions to transfer data and files to and from the 
remote host computer, hjsend and h_recv are more efficient than the Copy 
functions when your are copying many screens of data. 

Automating Keystrokes 

Your application program may provide all of the keystrokes for another 
application or may mingle keystrokes to the target destination with those 
from the keyboard. In order to do this, your application must occasionally 
lock out other sources of keystroke input that may be destined for a target 
application or presentation space. This can be done by calling the h_resv 
(Reserve) HLLAPI function. Your program can later unlock the target 
application or presentation space by calling the h_rel (Release) function. 

Filtering Keystrokes 

Your application program can act as a filter by intercepting a keystroke 
coming from HLLAPI (either from the keyboard or a source application) tar- 
geted ifor another destination. Once intercepted, the keystroke may then be: 

■ ignored (i.e., deleted) 

■ redirected to another application 

■ validated 

■ converted from upper case to lower case, or from ASCII to EBCDIC 



1-6 HLLAPI PROGRAMMER'S GUIDE 



The HLLAPI Tutorial 

The AT&T 3270 Emulator+ HLLAPI Tutorial is a menu-based full-screen 
interactive learning tool that allows you to invoke individual HLLAPI func- 
tions and see the results of executing these functions and the parameters 
returned by them without writing complex programs. You can also use the 
AT&T 3270 Emulator+ HLLAPI Tutorial as an informal testing tool. 

The AT&T 3270 Emulator+ HLLAPI Tutorial organizes the HLLAPI 
functions into the following seven menus: 

■ Local Environment Functions Menu — includes the HLLAPI func- 
tions that perform basic operational tasks. 

■ Communications Functions Menu — includes the HLLAPI functions 
that support transactions with the remote host computer. 

■ Keyboard Functions Menu — includes the HLLAPI functions associ- 
ated with handling terminal keystrokes between your application 
program and the remote host computer. 

■ File Transfer Functions Menu — includes the HLLAPI functions that 
allow an application program to transfer files between an AT&T 3B 
Computer and a remote host computer. 

■ Memory Management Menu — includes the HLLAPI functions that 
allow you to preallocate, free and query the blocks of storage used by 
the application program. 

■ Presentation Space Management Menu — includes the HLLAPI func- 
tions that support your application program by helping you manage 
the regions in storage where different screens are stored, copy data to 
and from these regions, and control how your screens will appear. 

■ Environment Functions Menu — includes the HLLAPI functions that 
provide access to the UNIX System. 

The AT&T 3270 Emulator+ HLLAPI Tutorial allows access to the UNIX Sys- 
tem shell from any of its menus. 
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The AT&T 3270 Emulator+ Application Program Interface (API) is a 
low-level version of the AT&T 3270 Emulator+ HLLAPI. It is also a library 
of C language functions that you can call from a C language application 
program to emulate the actions of a 3270 terminal operator. Just like the 
AT&T 3270 Emulator+ HLLAPI, the API allows your application program to 
communicate with remote host computers from an AT&T 3B Computer. 
However, the API provides two modes of accessing a remote host: 3270 data 
stream mode and "raw" data stream mode. In 3270 data stream mode, the 
application program, using either HLLAPI or API functions to communicate 
with the remote system, is functionally equivalent to the interactive user 
interface to the host through a 3278/9 terminal. The raw mode, only avail- 
able in the API, provides a raw data transfer interface that is independent of 
any terminal functionality (i.e., no 3270 data stream encoding /decoding is 
done). 

In general, the AT&T 3270 Emulator+ API is more difficult to learn and 
use than the AT&T 3270 Emulator+ HLLAPI. Therefore, the use of HLLAPI 
rather than API functions is recommended, except in those application pro- 
grams that must access the remote host computer in raw data stream mode. 



NOTE 



A Tutorial is also provided with the AT&T 3270 Emulator+ API. (See 
"The API Tutorial" in chapter 4.) 
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This section presents basic concepts that you will have to understand to 
use the AT&T 3270 Emulator+ HLLAPI. 



Host Session 

The communications between your application program and the IBM 
host computer are called host sessions. A host session is the logical connection 
between a presentation space and an application program running on a 
remote host computer. 



Presentation Space 

A presentation space is a region in computer storage that can be displayed 
on your terminal screen. 



NOTE 



The IBM 3270 Personal Computer can display several windows on the 
screen. The AT&T 3270 Emulator+ HLLAPI allows you to view one 
window at a time, and this window occupies the size of the entire 
screen. 



The current connected presentation space is the active session to which you are 
connected. 



WS Ctrl 

WS Ctrl (Work Station Control) is treated as a session type by HLLAPI, 
even though it is really a "pseudo-session." As a pseudo-session, WS Ctrl can 
call functions against other sessions, such as copy blocks of text from one 
session to another. But there is no presentation space associated with the WS 
Ctrl session. 
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Operator Information Area (OIA) 

The Operator Information Area (OIA) is the bottommost line of the screen 
that displays information about the status of your workstation and the 
remote host computer. 



Attention Identifier Keys 

The Attention Identifier (AID) keys are non-ASCII control keys: PF, PA, or 
Enter. 



Combination Keys 

Combination keys must be used with another key or keys to produce a 
desired function. Examples are the Control and Shift keys. 
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The AT&T 3270 Emulator+ HLLAPI functions are classified into seven 
groups, according to the services that they provide to an application pro- 
gram. There are: 

■ Local Environment Functions 

■ Communications Functions 

■ Keyboard Functions 

■ File Transfer Functions 

■ Storage Manager Function 

■ Presentation Space Functions 

■ Environment Functions 

Each HLLAPI function is associated with a Symbolic Name, and a Func- 
tion Number. The Symbolic Name of a function is the name that you use to 
refer to that function in a C application program. The Function Number of 
a function is the number used by the IBM 3270 Personal Computer HLLAPI to 
refer to that function. 

The following sections describe the HLLAPI function groups. Each 
description includes the HLLAPI functions that are part of that group, along 
with their Function Numbers and Symbolic Names. This information is 
useful if you are familiar with the IBM product and want to write C 
language application programs using the AT&T 3270 Emulator+ HLLAPI. 



Local Environment Functions 

The AT&T HLLAPI Local Environment Functions perform basic opera- 
tional tasks that support the interface between your HLLAPI application 
program and its copy of the HLLAPI library. These functions are summar- 
ized below. 
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Function Name 


Function Number 


Symbolic Name 


Connect Presentation Space 


1 


HjCONNECT 


Disconnect Presentation Space 


2 


H_DISC 


Set Session Parameters 


9 


HjSETPARMS 


Query Session 


10 


H_QSESS 


Reserve 


11 


H_RESV 


Release 


12 


HJREL 








Query System 


20 


H QSYS 


Reset System 


21 


H RESET 


Query Session Status 


22 


H QSTATUS 


Connect and Interact with 


113 


H CONNINT 


Presentation Space 







Communications Functions 

The AT&T HLLAPI Communications Functions represent the fundamen- 
tal set of functions that support transactions with the remote host computer. 
These functions are: 



Function Name 


Function Number 


Symbolic Name 


Send Key 


3 


HJSENDKEY 


Wait 


4 


H WAIT 


Pause 


18 


H PAUSE 


Start Host Notification 


23 


H STRTHOST 


Query Host Update 


24 


H QHOST 


Stop Host Notification 


25 


H STOPHOST 
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Keyboard Functions 

The AT&T HLLAPI Keyboard Functions are the set of function calls 
associated with handling terminal keystrokes between your application pro- 
gram and the host computer. These functions are: 



Function Name 


Function Number 


Symbolic Name 


Start Keystroke Intercept 


50 


H STARTKEY 


Get Key 


51 


H GETKEY 


Post Intercept Status 


52 


H POSTINT 


Stop Keystroke Intercept 


53 


H STOPKEY 



File Transfer Functions 

The AT&T HLLAPI File Transfer Functions allow an HLLAPI applica- 
tion program to transfer files between an AT&T 3B Computer and an IBM 
host. The two File Transfer Functions are: 



Function Name 


Function Number 


Symbolic Name 


Send File 


90 


H SEND 


Receive File 


91 


H_RECV 



Storage Manager Function 

The Storage Manager Function preallocates blocks of storage for use by 
certain HLLAPI functions. 

You can make the following subfunction calls to the Storage Manager 
Function: 

■ Get Storage 
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B 



Free Storage 
Query Free Storage 
Free All Storage 



Function Name 



Function Number Symbolic Name 



Storage Manager 



17 



H STMAN 



Presentation Space Functions 

The AT&T HLLAPI Presentation Space Functions provide support for 
your application program by helping you manage presentation spaces, copy 
data to and from various regions of storage, and control how your screen 
will appear. 

The Presentation Space Functions are summarized below. 
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Function Name 


Function Number 


Symbolic Name 


Copy Presentation Space 


5 


H_COPY 


Search Presentation Space 


6 


H_SEARCH 


Query Cursor Location 


7 


HjQCUR 


Copy Presentation Space to String 


8 


H_COPYPSS 


Copy OIA 


13 


H_CPOIA 


Query Field Attribute 


14 


H_QATTR 


Copy String to Presentation Space 


15 


H_CPSTR 


Search Field 


30 


H SRCHFLD 


Find Field Position 


31 


H_FNDPOS 


Find Field Length 


32 


H_FNDLEN 


Copy String to Field 


33 


H_CPSTRF 






H PPFTFT D 


Convert Position or RowCol 


99 


H_CONV 


Change Cursor Position in 


111 


H_CHCUR 


Presentation Space 






Write a Character in Presentation 


112 


H_WRCHAR 


Space 







Environment Functions 

The AT&T HLLAPI Environment Functions provide direct access to the 
UNIX System. Your application program can execute UNIX System com- 
mands or programs and place the resulting data in the program segment 
following the function call or pipe it to other processes. The two Environ- 
ment Functions are shown below. 



Function Name 


Function Number 


Symbolic Name 


Invoke UNIX System Com- 


92 


HJNVOKE 


mand or Program 






UNIX Redirect 


93 


H_REDIR 
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You can use an AT&T 3270 Emulator+ HLLAPI function by coding the 
hllapi function in your application program with a set of data arguments 
referred to as calling parameters. After executing the function call, the hllapi 
function returns certain parameters that your application program might use 
in an error routine. 

Both the calling parameters and the returned parameters vary depend- 
ing on the HLLAPI function that you are trying to call. An overview of 
these parameters follows. 



Calling Parameters 

The AT&T 3270 Emulator+ HLLAPI functions are called by invoking 
hllapi in your application program, as follows: 

#include <xhllapi.h> 

int hllapi(func,data4ength,position) 
int *func; 
char "^data; 
int * length; 
int ^position; 

The data arguments passed to the hllapi function are: 

*func is a pointer to the desired function code, preferably 

in the form of a symbolic name for the desired func- 
tion. This parameter is always required. 

"^data This argument is used in different ways by different 

functions; in some functions it is a pointer to a char- 
acter array, while in others it is a pointer to a struc- 
ture. 

*length This argument usually points to the length of what- 

ever the data parameter points to. 

"'position is a pointer to a value associated with the emulated 
3278/3279 Display Station screen position. This 
value can be: 
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□ 1 through 1920 for Model 2's, or 

□ 1 through 3564 for Model 5's 

You must provide all parameters when making a func- 
tion call. You can use a filler variable for those function 
calls that do not require all parameters. 

The xhllapi.h file that you must include in your applica- 
tion program with #include defines the symbolic names for 
the AT&T HLLAPI functions and return codes, and the 
structure identifiers used by several HLLAPI functions. This 
file is listed in Appendix C, The xhllapi.h File. The xhllapi.h 
file does not define storage; you are responsible for allocat- 
ing the storage buffers required by your application pro- 
gram. 



Returned Parameters 

The AT&T 3270 Emulator+ HLLAPI function calls return a return code 
from Figure 2-1. For example, if you made the following call in your appli- 
cation program 

y = hllapi(funC/data,length,position) 

the variable y would be assigned one of the return code values shown in 
Figure 2-1. These values inform your application program of the success, 
failure or status of the function call. This information might be used by an 
error handling routine in your application program. 

In addition, the AT&T 3270 Emulator+ HLLAPI function calls return 
requested information at the locations pointed to by the calling parameters, 
as shown below; not all four parameters will be changed on return for each 
function call. 

""func This parameter is not changed. 

*data This parameter returns different information, 

depending on the function; in some functions, it 
points to a string of characters, in others to a struc- 
ture. 
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*length usually points to the length of whatever the data 

parameter points to, although a position can be 
returned in this field. 

^position The function return code described above is also 

placed at the location pointed to by this parameter. 

The manual pages for the HLLAPI function calls describe the return 
codes that apply to each individual function call, although the general 
meanings are consistent with the standard return codes shown below. This 
consistency allows you to use a common error-handling routine in your 
HLLAPI application program. 



Return 


Symbolic 




Code 


Name 


Description 


0 


HEJSUCCESS 


good return 


1 


HEJNVAL 


you specified an invalid presentation 






space 


2 


HE_PARM 


a parameter error was encountered, or 






an invalid function was specified 






(refer to the individual function for 






details) 


3 


HE_WSCTRL 


WS Ctrl action has occurred 


4 


HE_BUSY 


the target presentation was busy 


5 


HEJNHBT 


the execution of this function was 






inhibited for some reason different 






than the one stated in return code 4 


6 


HE_LENGTH 


a data error was caused by an invalid 






length parameter specification 


7 


HE_POS 


you specified an invalid presentation 






space position 


8 


HE_PROC 


a functional procedure error was 






encountered 


9 


HE_SYSERR 


a system error was encountered 


10 


HE_FUNCT 


function unavailable 
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Return 


fivmlinlir 




Code 


Name 


Description 


11 


HE RSC 


the resource that you requested is una- 






vailable 


21 


HE_OIA 


updated OIA 


22 


HE_PRES 


updated presentation space 


23 


HE BOTH 


both of the above have been updated 


24 


HE_NOFIELD 


no such iGleld 


25 


HE_NOKEYS 


requested keys are not available 


26 


HEJJPDATE 


a host presentation space or OIA has 






been updated 


301 


HE_FNUM 


invalid function number 


302 


HE_NOENT 


file not found 


305 


HE_ACCESS 


access denied 


308 


HE_MEM 


insufficient memory 


310 


HE_ENV 


invalid environment 


311 


HE_FORM 


invalid format 


8000 


HE_DATA 


only data portion has been updated 


9998 


HEJPSID 


invalid presentation space 


9999 


HE_NOTPR 


parameter was not 'p' or Y 



Figure 2-1: HLLAPI Return Codes 



Linking Your Application Program 

Once you have written your application program, you must link it with 
the AT&T HLLAPI library. You can do this at compile time by using the 
command line: 

cc -o userjipplication_program.c -Ihllapi -lapi -Icurses -Igenusr 
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Environment Variables 



The AT&T 3270 Emulator+ HLLAPI uses the environment variables that 
are set and exported by the snaenvset or bscenvset shell scripts. In addi- 
tion, the AT&T HLLAPI uses the following UNIX System environment vari- 
ables and files: 



KY3278 
LUPORT 

LUTABLE 
P3274 

RTMSG 

SC3278 
STSIZE 



TE3279.MSG 
TM3279 



name of the keyboard customization file (object file) 

contains the logical channel to be used for a particu- 
lar session. If this environment variable is NULL, 
the LUPORT uses the next available logical channel. 

file name for LUTABLE 

named pipe to the controller process (e.g., sna or 
tm3274) 

path name for the location of the run-time message 
file 

name of the screen customization file (object file) 

maximum storage size that you can allocate, using 
the Storage Manager Function. A practical max- 
imum value is 64K, or the amount left over in the 
address space by the hllapi process, including your 
application program (your application program is 
linked with the hllapi library) 

name of the 3279 terminal message file 

terminal model, either 2 or 5 



Refer to the AT&T 3270 Emulator+ System Administrator's Guide for more 
information on both the snaenvset and bscenvset scripts and the environ- 
ment variables listed above. 
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The LUTABLE file describes the logical units (LU's) that will be 
assigned to the controller type, hllapi will first look in your home directory 
to see if there is an LUTABLE file. If not, the file defined by the LUTABLE 
environment variable (above) will be used. You or the System Administra- 
tor for your installation can restrict access to the LUTABLE file in your 
home directory (see chmod(l) in the UNIX System V User's Reference Manual 
and chmod(2) in the UNIX System V Programmer's Reference Manual). This 
feature provides additional security, since it in turn restricts hllapi use. 

Your application program can interact with up to 4 presentation spaces, 
although at any given time it can only be connected to one. Therefore, the 
LUTABLE contains a maximum of 4 entries, with a maximum of 6 fields in 
each entry. Each entry in the LUTABLE file contains the following fields, 
separated by blanks: 

■ The presentation space short name. You can use any capital letter 
from A through Z in the presentation space short name, but no 
numbers. 

■ The presentation space long name. You can use any combination of 
8 characters, excluding white space characters (space and tab). 

■ LU number(s) or number range: the AT&T 3270 Emulator+ allows 
up to 32 LU's to be connected at any given time, numbered from 0 
through 31. LU numbers are decimal digits separated by commas; LU 
number ranges are separated by dashes. 

■ The name of the controller pipe. 

■ The terminal model number, either 2 or 5. 

■ An extended-attribute-bytes indicator, either a 'y' or a blank. 



The LU number is equivalent to the host LU address minus 2, as 
NOTE defined in the LU-Macro Locator Field. 
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Figure 2-2 shows a sample LUTABLE file. This file contains three 
entries that define three presentation spaces associated with the user appli- 
cation program. The first entry contains the presentation space short name 
"T," the presentation space long name "one," and the LU numbers 0 through 
2. The name of the controller pipe, and the terminal model are not 
specified; therefore, the default values will be used. The default values are 
those that were assigned to the environment variables. 

The second entry contains the presentation space short name "U," the 
presentation space long name "two," and the LU numbers 5 through 17. 
The two fields that follow contain a dash (-); this means that default values 
will be used for the name of the controller pipe and the terminal model. 
The last field contains a 'y,' which indicates that extended attributes will be 
used. 

The last entry in Figure 2-2 is similar to the second entry, except that 
the terminal model is specified, the extended attributes field is left blank, 
and three non-consecutive LU numbers are specified. 




Figure 2-2: Sample LUTABLE 
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Introduction 



The AT&T 3270 Emulator+ HLLAPI Tutorial is a useful interactive 
learning tool that allows you to invoke individual HLLAPI functions, and 
see the results of executing these functions and the parameters returned by 
them without writing complex programs. You can also use the AT&T 3270 
Emulator+ HLLAPI Tutorial as an informal testing tool. 

The AT&T 3270 Emulator+ HLLAPI Tutorial runs through two separate 
programs: hllapiprim, and hllapisec. hllapiprim is the primary program 
that prompts you for the function name and the parameters required by the 
function that you want to execute. These parameters are passed to the 
secondary program, hllapisec, after have you entered the information 
requested by hllapiprim. hllapisec then shows the effect of executing the 
function call and the parameters returned by the function. The following 
section describes the actions that you should take to use the AT&T 3270 
EmulatorH- HLLAPI Tutorial. 
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You can run the hllapiprim and hllapisec programs on the same termi- 
nal or on different terminals. When using one terminal, invoke the hllap- 
isec program first as a background task, with the standard output and the 
standard error directed to files to avoid cluttering the screens. 



NOTE 



Your application program cannot establish a physical connect with the 
presentation space if hllapisec is running in the background 



For example, typing in the command 

hllapisec 1 > seoout 2 > &.1 &. 

redirects the standard output and the standard error to the file secout; you 
may use another file name if you like. Next, enter 

hllaplFrim 

If you are using two terminals, the order in which you invoke the two 
AT&T 3270 Emulators- HLLAPI Tutorial programs does not matter; on one 
terminal, enter 

hllapiprim 

on the other 

hllapisec 

See "The Environment" section in chapter 2 for information regarding 
environment variables that must be set before running the hllapiprim and 
hllapisec programs. 

The hllapiprim program is a menu-based full-screen interactive pro- 
gram that organizes the functions supported by the AT&T 3270 Emulator+ 
HLLAPI into seven menus: 

■ Local Environment Functions Menu 

■ Communications Functions Menu 
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■ Keyboard Functions Menu 

■ File Transfer Functions Menu 

■ Memory Management Menu 

■ Presentation Space Management Menu 

■ Environment Functions Menu 

Once you invoke the hllapiprim program, the main menu will appear on 
the screen listing these menus, as follows; 




1 - Lcx:al Environment Functions Menu 

c - Qannunicatians Functions Menu 

k - Keyboard Functions Menu 

f - File Transfer Rmcticsis Mem 

m - Manary Manageaient Menu 

p - Presentation Space Wanageaeat Menu 

e - Envircnment Functions Menu 

q - Quit the HLLAFE 'Ritorial 



Select a choice: 




The top portion of each menu screen lists the functions in the menu, 
and the bottom portion shows the menu-switching commands and other 
available response choices. 

The region between the top and bottom portions of each screen is the 
user interaction area; you will be prompted to enter choices, and the results 
will be displayed in this area. You can respond to the "Select a choice:" 
prompt on each screen with a function number or with any of the valid 
commands listed at the bottom of the menu. Furthermore, if you respond to 
the "Select a choice:" prompt with a !, you will escape to the UNIX System 
shell program defined by the SHELL variable. If you respond with an x. 
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the latest parameters returned by a function are placed in a text file in hexa- 
decimal format. The editor program defined by the EDITOR environment 
variable will then be invoked, and the text file will be displayed. Typing in 
an X at the "Select a choice:" prompt lets you see the non-displayable char- 
acters and save the results in files for later use. 

For example, after you have run the AT&T 3270 Emulators- HLLAPI 
function number 5 (Copy Presentation Space), the x command might pro- 
duce the following display: 



FUNCTION 5 

0000 74686973 20697320 74686520 72657375 
0010 6c74206£ 6620636£ 70792070 72657365 
0020 6e746174 696£6e20 66756e63 74696£6e 
0030 2063616c 6c 

0000 34 



*this . is . tihe . resu* 
*lt . o£ . copy, prese* 
*ntaticn. functicin* 
*call* 



*4* 



The seven AT&T 3270 Emulators- HLLAPI Tutorial menus that may be 
called from the HLLAPI Tutorial Main Menu are shown below. 
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1 


- Coamect PS 


16 


- Vfork Station Control 


2 


- Discxamect PS 


20 


- Query system 


9 


- Set Session Param 


21 


- Reset System 


10 


- Query Sessions 


22 


- Query Session Status 


11 


- Reserve 


113 


- Connect and Interact vdth PS 


12 


- Release 







Select a choice: 



1 - Log Env Menu f - File Trans Menu e - Env Menu x - hex return 
c - Ccncuni Menu m - Memory Manag Menu M - Main Menu 1 - shell 
k - Kie^x>arcl Menu p - PS Maaag Menu q - qiiit 



Cconunications Functions Menu 



3 - Send Key 23 - Start Host Notification 

4 - WEdt 24 - Query Host Update 

18 - Pause 25 - Stop Host ttotification 



Select a choice: 



1 - Loc Env Menu f - File Trans Menu e - Env Menu x - hex return 
c - Gcnnuni Menu m - Memory Manag Menu M - Main Menu I - shell 
k - Kei^xjard Mem p - PS Manag Menu q - quit 
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50 - Start KeyboaaA Intercept 52 - Post Intercept status 

51 - Get Key 53 - Stop Keystroke Intercept 



Select a choice: 



1 - Loc Env Menu £ - File Trans Menu e - Env Menu x - hex return 
c - Gonnuni Menu m - Memory Mdoiaq Menu M - Nciiii Menu 1 - shell 
k - K^jtoaxd Menu p - FS Manag Kena q - quit 




90 - Serxa File 

91 - Receive File 



Select a choice: 



1 - Loc Env Menu £ - File Trans Menu e - Env Menu x - hex return 
c - Ccnnuni Menu m - Memory Manag Menu M - VSadn Menu I - shell 
k - Keyboaocd. Menu p - PS Manag Menu q - quit 
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17 - Storage Manager 
Select a choice :_ 



1 - Loc Env Mem f - Bile Trans Menu e - Env Menu x - hex return 
c - Ccmiuni Menu m - Memory Manag Menu M - Main Menu 1 - shell 
k - Keytxiard Menu p - PS Manag Menu q - quit 




5 


- Copy Presentation Space 


31 


- Find Field Position 


6 


- Seeirch Presentation Space 


32 


- Find Field Length 


7 


- Query Cursor locaticn 


33 


- Copy String to Field 


8 


- Copy PS to String 


34 


- Copy Field to String 


13 


- Copy OIA 


99 


- Convert Position or PowCol 


14 


- Query Field Attrihute 


111 


- Change Current PS Position 


15 


- Copy String to PS 


112 


- Mrite a Character in PS 


30 


- Search Field 







Select a choice: 



1 - Loc Env Menu f - File Trans Menu e - Env Menu x - hex return 
c - Ccmiuni Menu m - Memory Manag Menu M - Main Menu I - shell 
k - Kie^x»rd Menu p - PS Manag Menu q - quit 
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92 - Invoke UNIX Process 

93 - UNIX Redirect 



Select a choice: 



1 - Log Env Menu f - File Trails Menu e - Env Menu x - hex return 
c - Ccnnuni Menu m - Hennry Manag Menu M - Main Menu I - shell 
k - KeyboaocA Menu p - PS Manag Menu q - qiiit 




To avoid switching back and forth between menus, you can execute any 
valid AT&T 3270 Emulator+ HLLAPI function from all menus, including 
the Main Menu; this is useful for experienced HLLAPI users, or when you 
must execute a sequence of HLLAPI calls. 

Once you choose a function by entering a function number in response 
to the "Select a choice:" prompt, you will be asked to enter the calling 
parameters required by that function. For example, 

Data<- 

prompts you to enter the data string parameter, 
Length<- 

prompts you to enter the length parameter, and 
Retcxxie<- 

prompts you for the return code parameter. 

Since not every function requires all parameters, you will only be asked 
to provide the parameters required by the function you have chosen. How- 
ever, if the length parameter can be derived from the data string parameter, 
the AT&T 3270 Emulator+ HLLAPI Tutorial will automatically compute the 
length parameter and display it on the screen. You then have the option of 
changing the length parameter or pressing the return key to enter it. The 
parameters returned by the function will be displayed on the screen with 
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their labels once the function has executed. 

The AT&T 3270 Emulator+ HLLAPI Tutorial will add a + character at 
the end of the returning parameters, if their content exceed the width of 
the physical screen; non-displayable characters will appear as spaces. Use 
the X command to view the entire contents of the returning parameters, . 
and non-displayable characters. 

Editing Mode 

Whenever you are prompted for entries on any of the AT&T 3270 Emu- 
lator+ HLLAPI Tutorial menus, your terminal is placed in the tutorial edit- 
ing mode. In this mode all characters typed, except the backspace, tilde, 
escape, and return characters, are immediately saved in an hllapiprim inter- 
nal buffer. The normal UNIX System erase and kill characters (# and @ ) 
are not interpreted as such, and do not have to be preceded by a The 
non-displayable characters (such as control characters) appear as spaces on 
the screen. 

A backspace character moves the cursor backwards one position and 
erases the current character and all characters to its right. The return char- 
acter ends the editing mode; the content of the buffer is taken as input to 
the current prompt, and the next prompt, if required, is displayed. In edit- 
ing mode, you can not move the cursor beyond the rightmost position on 
the screen; a bell will sound if you try to. 

When you enter the escape character from any position, the editor 
specified by the EDITOR variable will be invoked with the current buffer 
content. Use the escape character to enter characters beyond the rightmost 
screen position and to respond to menu prompts with the full-screen editor 
you prefer. This character is also useful if you must enter data for functions 
that require hundreds of characters or data that contains large numbers of 
non-displayable characters. 

When you leave the editor, the file content, which you must write out if 
you made changes, will be transferred to the hllapiprim internal buffer and 
the original screen will be redisplayed with the new buffer contents. When 
the buffer content is read by the editor, newline characters will be 
appended to break it into lines for readability and to circumvent possible 
line-length limitations; when files are copied back to the buffer, these new- 
line characters will be removed. If you have to enter a newline character 
into the buffer from the file, place it on a line by itself. 
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If the escape character is preceded by a tilde character, the buffer con- 
tent will be converted into hexadecimal format before the editor is invoked. 
The hexadecimal format file content is similar to the result of executing the 
"x" command: each line shows the address, hexadecimal displays of 16 char- 
acters followed by their corresponding character displays. 

Once inside the editor, the hexadecimal display portion can be edited 
using hex representations of characters. Note that when editing the hexa- 
decimal file, the file format must be preserved in order for the file to be 
converted properly back to the internal buffer; i.e., hex codes must be in 
groups of 4 characters separated by space characters and each line should 
have six characters before the first hexadecimal code, although the address 
portion is never used when file content is transferred to the internal buffer. 
This tilde-escape editing makes it possible for a user to enter any character 
as part of a function parameter input, including the four editing control 
characters and non-ASCII characters with embedded null characters. For 
example, using the tilde-escape editing, the storage address returned by the 
HLLAPI function number 17 (HjSTMAN - Storage Manager) can be entered 
as part of the data parameters for function number 23 (HJSTRTHOST - Start 
Host Notification). 

You can interrupt the editing mode with the interrupt signal or with 
the quit signal. The interrupt signal ends the current editing mode and 
moves the cursor to the "Select a choice:" prompt; all input parameters that 
you entered will be discarded, and the chosen function will not be exe- 
cuted. The quit signal ends the AT&T 3270 Emulator+ HLLAPI Tutorial 
program. 
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Environment Variables 

The hllapiprim and hllapisec programs communicate through two 
named pipes that they create if needed. The location of these two named 
pipes is, by default, the $HOME UNIX System directory; if the HOME 
variable is not defined or has no value, the current working directory will 
be used. The default file names for the two named pipes are .hlltutp.l and 
.hlltutp.2; however, you can set the environment variables HLLTUTDIR 
and HLLTUTP to override the default pipe names and locations. The AT&T 
3270 Emulator+ HLLAPI Tutorial will add the suffixes .1 and .2 to the 
names defined by HLLTUTP; therefore, you must restrict HLLTUTP names 
to a length of 12 characters. 

The AT&T 3270 Emulators- HLLAPI Tutorial uses two additional 
environment variables; EDITOR, and SHELL. EDITOR determines the 
text editor program that the AT&T 3270 Emulator+ HLLAPI Tutorial will 
use (e.g., ed or vi); the default is ed. SHELL determines the shell program 
that will be used when you escape to the UNIX System while running the 
AT&T 3270 Emulator+ HLLAPI Tutorial; the default is sh. 

You should also initialize other environment variables and /or files, as 
required by the AT&T 3270 Emulator^-. (See the AT&T 3270 Emulator+ Sys- 
tem Administrator's Guide for further information on this subject.) 
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Introduction 



The API provides two modes of accessing a remote host: in 3270 data 
stream mode or in "raw" data stream mode. In 3270 data stream mode, the 
application program interface to the remote system is functionally 
equivalent to the interactive user interface to the host through a 3278/9 ter- 
minal. The raw mode provides a block data transfer interface, independent 
of any terminal functionality. 

The following calls constitute the API interface: 

xlu2clos(3X) power off the logical unit 

xlu2ctl(3X) logical unit control functions 

xlu2func(3X) perform special functions on logical unit 

xlu2gets(3X) get a string from the LUD_3270 logical unit's screen buffer 

xlu2info(3X) obtain 3278/9 status line and cursor position information 

xlu2init(3X) initialize terminal function library 

xlu2intr(3X) interrupt an API call 

xlu2open(3X) power on the logical unit 

xlu2puts(3X) put a string to the LUD_3270 logical unit's screen buffer 

xlu2read(3X) read the next raw segment on the LUD_RAW/LUD_TRAW 
logical unit 

xlu2seek(3X) position the cursor to a field in screen buffer for LUD_3270 
logical unit 

xlu2writ(3X) write a raw segment on the LUD_RAW/LUD_TRAW logical 
unit 



where: 

logical unit is an SNA or a BSC terminal port. Logical unit is used 
generically, and it applies to both SNA and BSC. 

LUD_3270 specifies that the application program is using a terminal 
interface to the remote system 
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specifies that the application program is using a block 
data interface to the remote system; API does not exam- 
ine or alter the data except for BSC control codes, which 
are stripped before the data are passed to an application. 
In the case of SNA, API presents the RU to the applica- 
tion 

specifies that the application program is using a tran- 
sparent block data interface to the remote system; API 
does not examine or alter the data except for BSC control 
codes, which are stripped before the data are passed to 
an application 



BSC Operation 

When operating in BSC mode, 3274 controller functions are performed 
by the BSC controller process, TM3274, and the communication board b3274 
program. 

TM3274 performs the device interface functions of a 3274 cluster con- 
troller, including establishing internal communication with each device 
emulation process as it powers up, and validating and /or assigning device 
addresses to devices as they power up. TM3274 interfaces with b3274, via 
the driver, to transfer data between the emulated device and communica- 
tions line, and it also handles the transfer of screen contents during copy 
commands. 

b3274 performs the protocol level functions of an IBM 3274-51C cluster 
controller operating in BSC mode, including data stream validation, termi- 
nal status maintenance, and reporting. It handles polling and device selec- 
tion, and it also controls BSC timing functions, including timing of line 
activities and sync insertion. 



SNA Operation 

When operating in SNA mode, 3274 controller functions are performed 
by the SNA process, SNA, and the communication board sdlc program. 



LUD_RAW 



LUD_TRAW 
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SNA emulates the SNA functions of an IBM 3274-51C cluster controller. 
It provides support for all protocols associated with the Path Control, 
Transmission Control (or Connection Point Manager), Session Control, Data 
Flow Control, and Presentation Services layers of SNA. 

sdlc emulates the link-level SDLC protocols as implemented on the clus- 
ter controller. 



Configuration Files 

An API application uses the following configuration files: 

■ screen control customization object file 

■ keyboard mapping customization object file 

■ message object file. 

In addition, the controller configuration object file (BSC or SNA) must 
be set up. 



Include Files 

Application programs are required to include the header file xlu2io.h, 
which contains all required definitions and includes all other required files. 
Other files of interest to developers are: 

xapi.h includes most definitions 

ctrl.c controls the components of the API function library (see 
"Linking with the API Library," below) to be linked. 
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The API Tutorial is intended to assist API programmers in gaining fami- 
liarity with API function calls. The tutorial allows you to enter API calls 
from a terminal and observe the results. The package operates interactively; 
a menu allows you to choose the call you want, and submenus allow you to 
specify options to the call. 

The following files are contained in the tutorial package: 

primary shell script 

secondary shell script 

mast 

slv 

README contains instructions 
show_it 

This section describes how to use the API Tutorial; installation of the 
package is not a prerequisite for developing or running API application pro- 
grams. Refer to the appropriate AT&T 3270 Emulator^ Release Notes for ins- 
tallation instructions. 



Running the API Tutorial Package 

You can run the tutorial using one or two terminals. If one terminal is 
used, only part of the results of each API call can be displayed interactively 
following the execution of the call. The remainder of the output can be 
sent to a file you designate and can be examined after the tutorial program 
is terminated. 

If two terminals are available, the primary script is run on one terminal 
and the secondary script on the other. If only one terminal is available, the 
secondary script should be run in the background with output directed to a 
file. 

Before you run these programs you must have the 3274 controller pro- 
cess (SNA or BSC) running, and you should also have read the AT&T 3270 
Emulator+ Application Programmer's Guide and have it available for reference. 
You must also create two named pipes in the directory that contains the 
tutorial. To create the pipes, you do the following: 
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Step 1. Log in as root. 

Step 2. Enter the following sequence of commands: 

od the_directory_where_you_have_storedJhe_Tutorial 
nilcnod pip1 p 
itOcnod pip2 p 

Running with Two Terminals 

If the package is to be run from two terminals, you must perform the 
following steps. (The two terminals are referred to as "Tl" and "T2.") 

Step 1. Log in on Tl and T2. 

Step 2. On both Tl and T2, type 

cxi the_directory_where_these_files_are_stored 

Step 3. On Tl, type 

./secxandary a b c . 

where: 

a is the screen file name 

b is the keyboard file name 

c is the name of the controller pipe 

For example: 

a could be 4410 (from SC.4410) 
b could be std (from KY.std ) 
c could be /tmp/p3274.4 

and you would enter: 

./seooixiary 4410 std /tnp/p3274.4 
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Step 4. On T2, type 

./primary 

This causes the following primary menu to be displayed: 




0. 


Exit fxon pn^ogram 


1. 


xl\i2open 


2. xlu2clos 


3. 


xlu2ctl 


4. xlu2gets 


5. 


XlT22plltS 


6. xlu2seek 


7. 


xlTi2iiifo 


8. xl\i2init 


9. 


xlvi2£unc 


10. xlu2Hrite 


11. 


xlvi2read 





Enter Option : 




If you select any option from 1 through 11a series of menu sub- 
screens will be displayed, each requesting you to enter a parame- 
ter associated with the call. After you have entered the last 
parameter, the output of the call (i.e. the return value of the call 
and the return value of certain parameters associated with the 
call) is displayed, generally followed by the primary menu. 

Step 5. You may now request execution of API calls. Your first two calls 
must be xlu2init followed by xlu2open. 

Step 6. The purpose of Tl is to display additional output from each API 
call as it is executed. To cause the API to display the output, you 
must use LUV TRC or LUV DSP as the luvmod parameter in the 
xlu2open call. Once the xlu2open call has been made, the screen 
on Tl will display the results of subsequent API calls. 

You can also display this output by using the same values for the 
luvmod parameter in an xlu2ctl call. 
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Step 7. You can now continue with other API calls, eventually closing 
each session you open with an xlu2clos call. 

Step 8. The tutorial continues to run even after all open sessions have 
been closed with calls to xlu2clos. It may be terminated by 
selecting option "0" in the primary menu. If you terminate the 
tutorial, any sessions still open from T2 will be closed. 

Running with One Terminal 

If the package is to be run from one terminal, both the primary and 
secondary scripts must be run from this terminal, and any output from an 
API call must be directed to a file. The following steps are required: 

Step 1. Type 

./secxandary a b c > log file & 

where a, b, and c are the same as in Step 3 above, and logfile is 
the file in which you want the output to be placed. 

Step 2. Type 

./priroaar/ 

to display the series of menus described in Step 4 above. Your 
first two calls must be xlu2init followed by xlu2open. You must 
use LUV_NTD for the luvmod parameter in the xlu2open call. 

Step 3. You can now continue with other API calls as in Steps 7 and 8 
above. 

Step 4. At the completion of the tutorial, you can enter 

cat logfile 

to obtain the output of the API calls you made. 
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The API user does not interface with any of the protocol levels of SNA 
or BSC. The application program interface can be an emulated formatted 
screen, an unformatted screen, or a data block (raw mode). The general pro- 
cedure for developing an API application is to write an application program 
using API function calls and then to link the compiled program with the 
API library. 



API Execution 

The associated SNA or BSC controller process must be running before 
you execute an API application. The application may be executed as a back- 
ground or a foreground process. If you do not choose to view the screen, 
the terminal emulation application program may be initiated from the com- 
mand line in the background, without monopolizing a terminal to execute 
the functions. However, if you prefer to view the application's interaction 
with the host as it occurs, the program requires a physical terminal and 
should be run in the foreground (see xlu2ctl(3X)). 



Application Program Development 

API programs are written in the C programming language. The follow- 
ing sections describe the development process in detail. 

Application Program Format 

An API user program takes the following general form: 



#iiiclude <xlu2io.h> /* API header file */ 

extern int errapi; /* API error codes */ 

main (argc, argv) /* user entry point »/ 

int argc; 
char *argv[]; 
{ 

unsigned dhar luchani; 



if ( (xlu2iiiit( . . . . ) == -1) /* initialize eoulator */ 
. . : /* error */ 
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if ( (xli:2open(&luchan1 , ... ) ~ -1) /* power on the logical unit and 

aoqaire logical unit channel number */ 

... ; /* error «/ 



For 3270 data stream mode: 



if ((xlu2ctl(SJ.uchan1, LDEVEMT, KX_NMSG ...)== -1) /* await next message */ 
... ; /* error */ 

if ( (xlu2seek(SJuchan1, ... ) == -1) /* positicn cursor to field for reading */ 
; /* error */ 

if ( (xlu2gets(Suluchan1, ... ) == -1) /» get a string fron screen buffer */ 
... ; /* error */ 

user processing 



if ( (xlu2seek(&luchan1 , ... ) — -1) Aposition cursor to field for writing*/ 

... ; /* error «/ 
if ((3clu2puts(&lucban1, ... ) == -1) /* put a string to screen buffer */ 

... ; /* error «/ 



if ((xlu2ctl(&luclhan1, LQEVEtnr, KX_£MrER ...)== -1) /* transmit screen */ 
; /* error */ 

or, for raw mode: 



if ((xlu2ctl(&lucihan1, LOEVENT, KHJUMSG ... ) ~ -1) /* await next message */ 

... ; /* error «/ 
if ( (xlu2read(&luchan1 , ... ) = -1) /* read a data segment */ 
; /* error */ 

user processing 



if ( (xlu2writ(Siluchan1 , ...)== -1) /* write a data segnient to host */ 
... ; /* error */ 
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if ((xlu2clos(&luchan1) == -1); /* power off logical channel «/ 

... ; /* error */ 
return 





Linking with tlie API Library 

When you link the API library with an application program, the result- 
ing interface to the SNA or BSC controller is equivalent to the 3278/9 termi- 
nal emulation process. A user application consists of a process containing 
the user application program and the API function library. 

You must compile the program with the specified API function library 
directory pathname. To save runtime memory, you may elect to exclude 
subsets of the API function library when linking the application object 
file(s). Library usage is determined by the emulation modes (and the associ- 
ated functionality) required in the application program. The library subsets 
are: 

■ without 3270 data stream processing (RAW) 

■ without 3279 screen output generation (VNON) 

■ with all functionality included 

ctrl.c controls the selection of the API function library components in 
generating one of the above subsets. The user specifies the functionality to 
be excluded by using — D in the command line followed by the name of the 
excluded subset. The following command compiles and links a sample user 
API program without 3270 data stream processing (RAW) and without 3279 
screen output generation (VNON). api and gemusr contain API library run- 
time functions. 

cc -o sanple sample. c H»AW -D7N0N /usr/lib/ctrl.c 
— lapi — Icurses — Igerausr 
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The Application Program Environment 

API controls the emulated terminal based on the physical attributes of 
standard input. Terminal emulator functions write the screen buffer to stan- 
dard output. Therefore, when screen update is enabled, standard input and 
standard output may be redirected, but standard input must be a terminal 
device. 

Signals 

An API application program can receive any signal except SIGPWR, 
which is reserved. When a signal is caught during execution of an API 
application, the signal catching routine cannot call any other API functions 
(except xlu2intr) since the signal may have occurred during execution of an 
API function and API does not allow concurrent calls from the same pro- 
cess. 

Signals do not automatically cause API function calls to be interrupted. 
xluZintr is provided to allow a signal catching routine to interrupt execu- 
tion of certain other (mainline) API functions. 

If screen update is enabled and an incoming signal interrupts an API 
function call, and if the signal catching routine terminates the process, the 
physical terminal (not the emulated terminal) may be left in raw mode. If 
an API application signal catching routine terminates a process, it is recom- 
mended that the physical terminal be removed from raw mode (see 
ICANON in termio(7)). 

3270 Data Stream Mode 

The following must be considered when using the 3270 data stream 
mode for screen updating: 

■ Data are exchanged between the host and the logical unit through 
the screen buffer. 

■ The logical unit's screen buffer may be examined or altered, one field 
at a time, using xlu2gets or xlu2puts, respectively. 

■ In this mode, the logical unit has the functionality of a terminal emu- 
lation session. 
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Raw Mode 

The following must be considered when using raw mode: 

■ Data are exchanged between the host and the logical unit in raw data 
block units. 

■ When data are received from the host for a raw mode logical unit, 
the data are acknowledged without any data stream analysis. 

■ Raw data blocks are retrieved with xlu2read and transmitted with 
xlu2writ API function calls. 

■ The application program must control the sequencing of the raw data 
blocks to form chains of blocks and /or commands. 

■ Outbound raw data from the host are received and queued by API 
internally; the queued data are provided to the user a segment at a 
time with each xlu2read call. 

■ The application program must issue an xlu2read call periodically in 
order not to overflow the internal queue of raw data from the host. 
E_DOVFLO is returned in errapi if overflow occurs on the logical 
unit while executing an API function call on a channel on which 
overflow has occurred. Otherwise, E_DOVFLO is indicated in the 
err_cond field of XLU2IBUF (see xlu2inf o) for the logical unit on 
which data were lost. 

Multi-Session 

An API application can establish up to four sessions with one or more 
hosts. This is done by making up to four xlu2open calls and using the 
returned value of lu_chan (the parameter that specifies the logical unit) in 
subsequent API function calls. 

In general, the value of lu_chan returned by an API call will be the same 
as the called value. However, under certain circumstances, the called and 
returned value may differ. All API calls, except xlu2init and xlu2open, 
must be issued with an active lu_chan (i.e., one obtained from an xlu2open 
call). The call may return with an lu_chan dififerent from the one used to 
issue the call under the following conditions: 

■ Only xlu2read and xlu2ctl with LUEVENT or LUEVIMED commands 
can return successfully with a different lu_chan. 
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□ The xlu2read call returns with the lu_chan which has the oldest 
queued data. 

□ An xlu2ctl call, with an LUEVIMED command which takes an 
argument of KY NMSG will, if any data are present, return with 
the lu_chan which corresponds to a session that has the oldest 
queued data. 

□ An xlu2ctl call, with an LUEVENT command which takes argu- 
ments of KY PEND or KY_WAIT, returns with the lu_chan that 
first fulfills the request. 

□ An xlu2ctl call, with an LUEVENT command which takes argu- 
ments of KY_ENTER, KY_CLEAR, KY_SYS_REQ, KY_PAn or 
KYJPFn performs the requested function on the lu_chan input to 
the call but returns to the application program with the lu_chan 
that first achieves keyboard unlock. 

■ All other API calls will only return a different lu_chan on failure, and 
the failure must be an E_TTY or EjCTRLIO error on the other chan- 
nel. 

□ Before API will return a failure on a different lu_chan, it will first 
validate all the parameters in the original call and, if the call 
required interaction with the controller process, wait for the con- 
troller process to acknowledge receipt of the call information 

□ An E_TTY or E_CTRLIO error on another channel does not neces- 
sarily indicate failure of the call on the input channel. 

Host Interaction 

The user application program uses API function calls to perform screen 
updates or host interactions. The API function terminates with a return 
statement. Communication with the controller and /or the host (by use of 
xlu2open, xlu2ctl with an LUEVENT command, xlu2writ, xlu2read, or 
xlu2clos functions) is conducted in a half-duplex manner, i.e., the API func- 
tion that initiates the communication does not return control to the user 
application program until the controller /host completes processing. In the 
case of xIu2open and xlu2ctl with an LUEVENT command, "keyboard 
unlock" must also occur. 
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Keyboard unlock signifies that communication with the host is no 
longer in progress. This is indicated by the disappearance of the WAIT 
message displayed by the terminal emulation process, in the Operator Infor- 
mation Area, during communication. It does not reflect the keyboard's 
lock /unlock state due to an inhibit condition such as: 

■ an invalid operation (e.g., illegal function) 

■ field overflow 

■ bad key translation 

■ wrong screen location access 

■ non-numeric data entered into a numeric field 

■ keyboard disabled by the host 

All the inhibit conditions listed above are cleared and true keyboard 
unlock is achieved before returning control to the user. 

It is not ensured that the requested API function has executed success- 
fully if it results in an inhibit condition or a 480 program check error (see 
Appendix E). For all conditions except the last (keyboard disabled), the API 
call will fail with an error indicating the cause of the inhibit. If the key- 
board is disabled by the host, the call will not fail for this condition. In this 
case, the user must determine the occurrence of the inhibit by examining 
ii]hb_lck and opia in the XLU2IBUF structure for the session (see xlu2inf o). 

For example, if the host disables the keyboard while an xlu2ctl call to 
send the ENTER key is being processed, the user program may have to reis- 
sue the same xlu2ctl call. Error messages for each API function call are 
listed on the manual page for that call and summarized in the Appendices. 

All xlu2ctl calls (except xlu2ctl with an LUEVIMED command) that per- 
form functions resulting in interaction with the host or the controller wait 
for "keyboard unlock" before returning to the application program. 

The xlu2ctl call with an LUEVENT command, which takes arguments of 
KY NMSG, KY PEND or KY WAIT, waits for its respective conditions to be 
satisfied before returning. Therefore, the application program must be sen- 
sitive to the state the lu chan session is in before and after one of the above 
xlu2ctl requests is executed. xlu2writ does not wait for keyboard unlock, 
but it does wait for the controller to acknowledge the transmitted data. 
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Introduction 



All function calls are based on this common format: 

■ The NAME part provides the name of the function call. 

■ The SYNOPSIS part summarizes the use of the function call. The 
following conventions apply: 

□ Boldface strings are literals and are to be typed just as they 
appear 

□ Italic strings usually represent substitutable argument prototypes 
and program names found elsewhere in the manual 

□ Square brackets [| around an argument prototype indicate that the 
argument is optional. When an argument prototype is given as 
'name' or 'file,' it always refers to a file name. 

n Ellipses ... are used to show that the previous argument prototype 

may be repeated 

□ A final convention is used by the commands themselves. An 
argument beginning with a minus plus +, or equal sign = is 
often taken to be some sort of flag argument, even if it appears in 
a position where a file name could appear. Therefore, it is 
unwise to have files whose names begin with +, or =. 

■ The DESCRIPTION part explains the function call at hand, and the 
calling parameters. 

■ The SEE ALSO part gives you pointers to related information. 

■ The NOTES section points out important technical information 
and/or areas where you should exercise caution. 

■ The RETURN CODES section explains the returning parameters. 

The HLLAPI and API function calls are organized alphabetically. All 
HLLAPI function calls begin with H_ prefix, while all API function calls 
begin with XLU2. 
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H_CHCUR(3X) (AT&T 3270 EmulatorH- HLLAPI) H_CHCUR(3X) 

NAME 

h_chcur — change cursor position in presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *£unc; 
char "^data; 
int ^length; 
int *position; 

DESCRIPTION 

h_chcur allows the application program to change the cursor position in the 
current connected presentation space. 

Calling arguments: 

■ func points to the symbolic HjCHCUR 

■ position points to the destination cursor position in the current con- 
nected presentation space 

■ data and length are not applicable to h_chcur 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

h_chcur returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_chcur 
call. 

The return code for h_chcur will have one of these values: 

HE_SUCCESS: h_chcur was successful 

HEJLNVAL: an invalid presentation space was specified 

HEJPOS: the specified presentation space position was invalid 

HEJSYSERR: a system error was encountered; call the h_qsys function 
to find out the reason for failure 
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H_CONNECT(3X) (AT&T 3270 EmulatoH- HLL API) H_C0NNECT(3X) 

NAME 

hjconnect — connect presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char "^data; 
int ^length; 
int "^position; 

DESCRIPTION 

h_connect establishes a connection between your HLLAPI application program 
and a specified presentation space. Your application program can only con- 
nect to one presentation space at a time, even though there are four sessions 
available to you. 

If you issue two h_connect function calls in a row, an automatic disconnect 
takes place before the second call is issued, and the first call is nullified even 
if the second one fails. 

You do not have to call h_connect before using these functions: 

• h_setparms - set session parameters 

• hjqsess - query session 

• h_wsctrl - WS Ctrl 

• hjstman - storage manager 

• h qsys - query system 

• h_reset - reset system 

• hjqstatus - query session status 

• hjqhost - query host update 

• hjstartkey - start keystroke intercept 

• h_^etkey - get key 

• h_postint - post intercept status 

• h_stopkey - stop keystroke intercept 

• h send - send file 

• h_recv - receive file 

• h_invoke - invoke UNIX system command or program 

• h_redir - escape to the UNIX system 

• hjconv - convert position or RowCol 

Calling arguments: 

■ func points to the symbolic H_CONNECT. 

■ data points to the short name of the target presentation space. The presen- 
tation space short name is a capital letter from A through Z, and it is the 
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first field for the entry in the LUTABLE environment file that corresponds 
to the target presentation space. 

■ length and position are not applicable to h_connect. 

SEE ALSO 

h_setparms(3X), h_qsys(3X). 

NOTES 

The parameters CONPHYS, CONLOG, DISPLAY and NODISPLAY under 
h_setparms affect connect. 

If you specified the CONPHYS option with h_setpamis, h_connect establishes a 
physical connection with the requested presentation space and transfers con- 
trol to the user at the terminal. If you specified the CONLOG option, 
h_connect establishes a logical connection and the HLLAPI application pro- 
gram will retain control. 

DISPLAY allows the terminal user to view the results of your HLLAPI appli- 
cation program during an h_connect function call (if you specified the CON- 
LOG option, above), while NODISPLAY does not. 

RETURN VALUES 

h_connect returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_connect 
call. 

The return code for h_connect will have one of these values: 

HE_SUCC: h_connect was successful, and the selected presentation 
space is unlocked and ready for input 

HE_INVAL: an invalid presentation space was specified 

HE_BUSY: h connect was successful, but the presentation space is 
busy 

HE_INHBT: h_connect was successful, but the presentation space is 
locked, i.e., input is inhibited 

HEjSYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 

HEJRSRC: This resource is unavailable, and the requested presenta- 
tion space is in use by another session; try again later 
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NAME 

h connint — connect and interact with presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int "^func; 
char *data; 
int *length; 
int *position; 

DESCRIPTION 

h_connint connects your HLLAPI application program to the specified presen- 
tation space in the same way that the h_connect would, and in addition, it 
transfers control to the user without application program involvement. The 
user can enter manual transactions interactively with the host session (e.g., a 
logon sequence), until an escape sequence is entered at the keyboard (ESC FD, 
unless customized in a different way). At this point, h_connint returns control 
to the application program, and the instruction following the h_connitit call 
will be executed. 

Calling arguments: 

B func points to the symbolic H_CONNINT 

■ data points to the target presentation space short name. The presen- 
tation space short name is a capital letter from A through Z, and it is 
the first field for the entry in the LUTABLE environment file that 
corresponds to the target presentation space. 

■ length and position are not applicable to h_connint 

SEE ALSO 

h_qsys(3X). 

NOTES 

h_connint is an AT&T 3270 Emulator+ HLLAPI extension; it is not part of the 
IBM 3270 Personal Computer HLLAPI specification. 

RETURN VALUES 

h_connint returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_connint 
call. 

The retiurn code for h_connint will have one of these values: 

HE_SUCCESS: h_connint was successful 

HE_INVAL: an invalid presentation space was specified 

HEJSYSERR: a system error was encountered; call the hjjsys function to 
find out the reason for failure 
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NAME 

hjconv — convert position or row /column 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunC/ data, length, position) 
int *func; 
char *data; 
int ^length; 
int ^position; 

DESCRIPTION 

The h_conv function converts a presentation space positional value into the 
display row /column coordinates, or the display row /column coordinates into 
the presentation space positional value, without changing the cursor position. 
hjconv takes into account the model number for the emulated host display 
type, and the corresponding presentation space size, when it makes the 
conversion. 

Calling arguments: 

■ func points to the symbolic H CONV. 

■ data points to the presentation space short name and "P" for convert 
position, or to the presentation space short name and "R" for convert 
row /column. The presentation space short name is a capital letter 

" from A through Z, and it is the first field for the entry in the LUT- 
ABLE environment file that corresponds to the target presentation 
space. 

■ length points to the row in the presentation space. 

■ position points to the column in the presentation space. 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

h_conv returns two arguments: 

■ the first argument is the row number, or "0" for incorrect input. This 
value is placed at the location pointed to by the length calling parameter. 

■ the second argument is a return code, defined in the <xhllapi.h> header 
file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the 
h_conv call. If you have established a common error handling routine, 
be sure to take into account that the return code for h_conv is really a 
status code. 

The return code for h_conv will have one of these values: 
HEJSUCCESS: incorrect input was provided 

> HEJSUCCESS: PS position or column 
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HE_PSID: an invalid presentation space ID was specified, or 

the presentation space was never connected 

HE NOTPR: the second character in the data string is not "P" or 

"R" 
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NAME 

h_copy — copy presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

The h_copy function copies the contents of the current connected presentation 
space into a data area, specified in your HLLAPI application program. 

The h_copy function translates the characters in a host presentation space into 
ASCII, and translates the attribute bytes and other characters not represented 
in ASCII into blanks. You can specify to print the original character values by 
using the ATTRB option under h_setparms (ATTRB - pass back all codes that do 
not have an ASCII equivalent, except EABs, as their original values; 
NOATTRB - change all unknown values to blanks). 

Extended attribute bytes are not copied unless you have specified EAB with 
h_setparms (EAB: pass the presentation space data with extended attribute 
bytes; NOEAB: pass only data). 

Calling arguments: 

■ func points to the symbolic HjCOPY 

■ data points to the target area, which should be the size of the presen- 
tation space that you want to copy 

■ length and position are not applicable to h_copy 

SEE ALSO 

h_copypss(3X), h_qsys(3X), h_setparms(3X). 

NOTES 

The target area for the copy must be twice the size of the presentation space if 
extended attribute bytes will be copied. 

If you want to copy a portion of a presentation space only, use h_copypss. 

RETURN VALUES 

h_copy returns two arguments: 

■ the first argument is the target area that contains the copied presentation 
space. This area is placed at the location pointed to by the data calling 
parameter. 

■ the second argument is a return code, defined in the <xhllapi.h> header 
file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the 
h_copy call. 

The return code for h_copy will have one of these values: 
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HE_SUCCESS: 

HEJNVAL: 
HE_BUSY: 

HEJNHBT: 
HE_SYSERR: 



(AT&T 3270 Emulator+ HLLAPI) H_COPY(3X) 

the presentation space contents were copied to the loca- 
tion specified by your application program; the target 
presentation space was active, and the keyboard was 
unlocked 

the presentation space was not connected, and the copy 
results are undefined 

the presentation space contents were copied, and the 
connected presentation space was waiting for host 
response 

the presentation space was copied, and the keyboard was 
locked 

a system error was encountered; use h_qsys to find out 
the reason for failure 
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NAME 

hjcopypss — copy presentation space to string 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func/ data, length, position) 
int *func; 
char *data; 
int ^length; 
int ^position; 

DESCRIPTION 

h_copypss copies all or part of the current connected presentation space into a 
data area, previously defined in your HLLAPI application program. 

The offset of the string into the presentation space is based on defining the 
upper left corner (row 1, column 1) as location 1, and the bottom right corner 
as the maximum screen size for the presentation space. The sum total of the 
offset plus the string length, cannot exceed the maximum screen size for the 
presentation space. 

h_copypss translates the character(s) in a host presentation space into ASCII, 
and the attribute bytes and other characters not represented in ASCII into 
blanks. If you do not want the attribute bytes translated to blanks, you could 
request that the original values be copied using the ATTRB option under 
h_setparms. 

Extended attribute bytes are not copied unless you specified EAB under 
h_setparms. 

Calling arguments: 

■ func points to the symbolic H_COPYPSS 

■ data points to the target data string 

■ length points to the length of data 

■ position points to the beginning offset of data 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

NOTES 

The sum value of the position offset + length cannot exceed the maximum 
size of the presentation space. 

RETURN VALUES 

h_copypss returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_copypss 
call. 

The return code for hjcopypss will have one of these values: 

HEJSUCCESS: the presentation space contents were copied to the appli- 
cation program, the target presentation space was active, 
and the keyboard was unlocked 
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HEJENVAL: your HLLAPI program was not connected to a presenta- 
tion space, and the copy results are undefined 

HEJPARM: an error was made in specifying the string length 

HE_BUSY: the presentation space contents were copied, and the 
connected presentation space was waiting for host 
response 

HE_INHBT: the presentation space was copied, and the keyboard was 
locked 

HE_POS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the h_qsys function 
to find out the reason for failure 
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NAME 

h_cpfield — copy field to string 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char "'data; 
int ^length; 
int ^position; 

DESCRIPTION 

The h_cpfield function transfers characters from a field within the current con- 
nected presentation space into a string. You can use hjndpos to find the posi- 
tion of the source field, and hjndlen to find its length. 

You can use h_q}field with both protected or unprotected fields in a field- 
formatted presentation space, i.e., a host presentation space. 

The h_cpfield function ends when one of the following conditions are met: 

• when it reaches the end of the source field 

• when it exceeds the length of the target string 

• when it reaches the end of the presentation space 

Calling arguments: 

■ func points to the symbolic H CPFIELD 

■ data points to the target data string 

■ length points to the length of the value pointed to by data 

■ position points to the position of the source field in the presentation 
space that will be copied 

SEE ALSO 

h_fndlen(3X), h_fndpos(3X), h_qsys(3X). 

NOTES 

No forward wrapping will occur, but there will be backwards wrapping if the 
given position is located before the start of a field in the presentation space. 

RETURN VALUES 

h_cp field returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_cpfield 
call. 

The return code for h_cpfield will have one of these values: 
HE_SUCCESS: h_cpfield was successful 

HE_INVAL: an invalid presentation space was specified; i.e., it was 
not connected, not configured, or it was labeled with an 
invalid name 
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HE_PARM: a parameter error was encountered 

HE_LENGTH: the data to be copied and the target string were not the 
same size. The data may not have been truncated 
because the string length may have been larger than the 
field copied 

HEJPOS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the hjsys function 
to find out the reason for failure 
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NAME 

hjcpoia — copy OIA 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 

int *func; 

struct cpoia *data; 

int "^length; 

int ^position; 

DESCRIPTION 

h_cpoia returns the operator information area (OIA) data from the current con- 
nected presentation. The OIA data provides information about the status of 
your work station and the IBM host computer. 

Calling arguments: 

■ func points to the symbolic HjCPOIA 

■ data points to a structure of type cpoia, where the information 
returned by h_cpoia will be placed, cpoia is defined in the 
<xhllapi.h> header file as follows: 

typedef unsigned char uchar; 

/* Copy OIA data string */ 

typedef struct { 

char cp_format; /* OIA Format byte */ 

char cp_image[80]; /* OIA Image Group */ 

/* OIA Indicator Group */ 

/* Group 1: On-line and screen ownership */ 

#define SETUP 0x80 /* Setup mode */ 

#defineTEST 0x40 /* Test mode*/ 

#define SSCPOWN 0x20 /* SSCP-LU session owns screen */ 

#define LUOWN 0x10 /* LU-LU session owns screen */ 

#define UNOWN 0x08 /* Online and not owned */ 

#define READY 0x04 /* Subsystem ready */ 
uchar group_l; 

/* Group 2: Character selection */ 

#define EXTEND 0x80; /* Extended Select */ 

#define APL 0x40 
#define KANA 0x20 
#define ALPHA 0x10 
#define TEXT 0x08 
uchar group_2; 
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/* Group 3: Shift state */ 

#define NUMERIC 0x80; 
#define SHIFT 0x40; 
uchar group_3; 



/* Numeric Shift */ 
/* Upper Shift */ 



/* Group 4: PSS group 1*1 

I* Group 5: Highlight group 1*1 

I* Group 6: Color group 1*1 



#define SELECT 0x80; 
#define INHERIT 0x40; 

uchar group_4; 

uchar group_5; 

uchar groupjS; 

/* Group 7: Insert */ 

#define INSERT 0x80; 
uchar group_7; 



/* Operator Selectable */ 
/* Field Inherit */ 



/* Insert mode */ 



/* Group 8: Input inhibited */ 



/* Group 8: Byte 1 */ 

#define CHECK 0x80; 

#define KEY 0x40; 

#define MACHINE 0x20; 

#define COMM 0x10; 

#define PROGRAM 0x08; 

#define RETRY 0x04; 

#define NWORKING 0x02; 

#define VBUSY 0x01; 

/* Group 8: Byte 2 */ 



#define BUSY 0x80, 

#define WAIT 0x40, 

#define SYMBOL 0x20, 

#define FUNCTION 0x10, 

#define TOOMUCH 0x08 

#define NENOUGH 0x04 

#define WRONG 0x02 

#de£ine NUMBER 0x01; 



/* Group 8: Byte 3 */ 
#define UNAUTH 0x40; 



/* Non-resettable machine check */ 
/* Reserved for security key */ 
/* Machine Check */ 
/* Communications Check */ 
/* Program check */ 

/* Device not working */ 
/* Device very busy */ 



/* Terminal busy */ 
/* Terminal wait */ 
/* Minus symbol */ 
/* Minus function */ 
/* Too much entered */ 
/* Not enough entered */ 
/* Wrong number */ 
/* Numeric field */ 



/* Operator unauthorized */ 
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#define UNAUTHM 0x20; 

#define IDEAD 0x10; 
#define WPLACE 0x08; 



/* Operator unauthorized */ 

/* minus function */ 

/* Invalid dead key combination */ 

/* Wrong placed */ 



/* Group 8: Byte 4 */ 



#define PENDING 


0x80; 


/* 


Message pending */ 
Partition wait * / 


#define PARTITION 


0x40; 


/* 


#deane SYSTEM 


0x20; 


/* 


System wait * / 


#define MISMATCH 


0x10; 


/* 


Hardware mismatch */ 


#define NCONFIG 


0x08; 


/* 


Logical unit not configured */ 
*/ 




/* at control unit 



/* Group 8: Byte 5 */ 

#define AUTOKEY 0x80; /* Autokey inhibit */ 

#define INPUT 0x40; /* Application program has */ 

/* operator input inhibited */ 



uchar group_8[5]; 

/• Group 9: PSS Group 2 */ 

/* Group 10: Highlight Group 2 */ 

/* Group 11: Color Group 2 */ 

#define SELECT 0x80; /* Selected */ 

#define DISABLE 0x40; /* Display disabled (Group 9 only) * 

uchar group_9; 
uchar group_10; 
uchar group_ll; 

/* Group 12: Communications error reminder */ 

#define ERROR 0x80; /* Communications error */ 

#define MONITOR 0x40;/* Response time monitor */ 

uchar group_12; 



/* Group 13: Printer 

#define CUSTOM 0x80; 

#define MALFUNC 0x40; 

#define PRINTING 0x20; 

#define ASSIGN 0x10; 

#define WHAT 0x08; 

#define PRINTER 0x04; 
uchar group_13; 



*/ 

/* Printer code not customized */ 

/* Printer malfunction */ 

/* Printer printing */ 

/* Assign printer */ 

/* What printer */ 

/* Printer assignment */ 
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/* Group 14 & 15: Reserved */ 

uchar group_14; 
uchar group_15; 

/* Group 16; Autokey play /record status */ 

#define PLAY 0x80; 
#define RECORD 0x40; 
uchar group_16; 

/* Group 17: Autokey abort/pause state */ 

#define OVERFLOW 0x80; /* Recording overflow */ 

#define PAUSE 0x40; 
uchar group_17; 

/* Group 18: Enlarge state */ 

#define ENLARGE 0x80; /* Window is enlarged */ 

uchar group_18; 
} cpoia; 

■ length points to the length of the location pointed to by data 

■ position is not applicable to h_cpoia 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

h_cpoia returns two arguments: 

■ the first argument is the information described by the structure of 
type cpoia, placed at the location pointed to by the data calling 
parameter. The members of the cpoia structure describe the follow- 
ing: 

cp_format: OIA format byte for the 3270 PC 

cp_image[80]: OIA image in host code points, with no extended 
attribute types. 

■ the second argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the h_cpoia call. 

The return code for h_cpoia will have one of these values: 

HEjSUCCESS: the target presentation space is unlocked, and the 
OIA data was successfully returned 
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HE_INVAL: the target presentation space is not connected 

HE_PARM: an error was made when specifying the string 
length, and the OIA data was not returned 

HE_BUSY: the target presentation space is busy, but the OIA 
data was returned 

HE_INHBT: the target presentation space is locked, but the OIA 
data was returned 

HEJSYSERR: a system error was encountered; use hjjsys to find 
out the reason for failure 
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NAME 

h cpstr — copy string to presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int "^func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

h_cpstr copies an ASCII data string directly into the current connected presen- 
tation space, at the location specified by the position calling parameter. The 
function continues until the data reaches the named calling string length, or 
until the data reaches a non-autoskip attribute byte (an unprotected, non- 
numeric field that does not force the cursor into the next alphanumeric 
unprotected field). The physical location of the cursor will remain unchanged 
once the copy is complete. 

The string length is assigned by either: 

• an explicit length value (if you selected the default value STRLEN 
using h_setpamis), or 

• an ending string delimiter EOT=n (if you selected STREOT using 
h_setparms). 

The input string should contain the appropriate extended attribute bytes fol- 
lowing each ASCII character if extended attribute bytes were specified tising 
the EAB parameter under h_setparms. 

Calling arguments: 

■ func points to the symbolic H_CPSTR 

■ data points to the ASCII string to be copied into the presentation 
space 

■ length points to the length of the location pointed to by data 

■ position points to the position in the presentation space where the 
copy will begin, between 1 and the maximum screen size for the 
presentation space 

SEE ALSO 

h_qcur(3X), h_qsys(3X), h_setparms(3X). 

NOTES 

If you want to place the string data at a specific cursor location, use hjjcur 
first to obtain the presentation space position of the cursor, and then place 
this value in the presentation space position calling parameter. 

The string to be copied can be no larger than 1920 characters (3840 if you are 
copying extended attribute bytes also) for Model 2, and 3564 characters (7128 
if you are copying extended attribute bytes) for Model 5. 
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RETURN VALUES 

h_cj)str returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_cpstr 
call. 

The return code for h_cpstr will have one of these values: 
HE_SUCCESS: h_cpstr was successful 

HEJINHBT: the target presentation space is protected or inhibited, or 
illegal data was sent to target presentation space (such as 
a field attribute byte) 

the copy was completed, but the data was truncated 
the specified presentation space position is invalid 



HE_LENGTH: 
HE_POS: 
HE SYSERR: 



a system error was encountered; call the hjjsys function 
to find out the reason for failure 
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NAME 

h_cpstrf — copy string to field 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char *data; 
int "'length; 
int ^position; 

DESCRIPTION 

The h_cpstrf functions transfers a string of characters into a target field in the 
current connected presentation space. This function can be used with both 
protected or unprotected fields in a field-formatted presentation space, i.e., a 
host presentation space. 

The calling data string parameter specifies the string that will be transferred; 
there is no wrapping during the process, and it ends when one of these four 
conditions is encountered: 

• an EOT is reached, if EOT mode was selected using h_setparms 

• the length of the string is reached 

• an end of field is encountered 

• the end of the presentation space is reached 

Calling arguments: 

■ func points to the symbolic H_CPSTRF 

■ data points to the string containing the data to be transferred to a tar- 
get field within the last connected presentation space 

■ length points to the length of the location pointed to by data. 

■ position points to the position of the target copy field 

SEE ALSO 

h_chcur(3X), h_qsys(3X), h_sendkey(3X), h_setparms(3X). 

NOTES 

The combined h_chcur and h_sendkey function calls will return control to your 
HLLAPI application program sooner than if you use h_cpstrf; use this combi- 
nation if response time is an important factor. 

RETURN VALUES 

h_cpstrf returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_cpstrf 
call. 

The return code for h cpstrf will have one of these values: 
HE_SUCCESS: h_cpstrf was successful 
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HEJNHBT: 

HE_LENGTH: 

HE_POS: 

HEJSYSERR: 



(AT&T 3270 Emulator+ HLLAPI) H_CPSTRF(3X) 

the target field was protected or inhibited, or illegal data 
was sent to the target field (such as a field attribute 
style) 

copy was completed, but data was truncated 

the specified presentation space position is invalid 

a system error was encountered; call the hjjsys function 
to find out the reason for failure 
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NAME 

h disc — disconnect presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

hjiisc drops the connection between your HLLAPI application program and 
the current connected presentation space. 

Calling arguments: 

■ func points to the symbolic H_DISC 

■ data, length, and position are not applicable to hjiisc 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

hjiisc returns one argument: a return code, defined in the <xhllapi.h> header 
file. The return code is placed at the location pointed to by the position calling 
argument, and is also returned as the function value for the hjiisc call. 

The return code for hjiisc will have one of these values: 

HE_SUCCESS: hjiisc was successful 

HE_INVAL: you are not currently connected to any presentation 
space 

HEJSYSERR: a system error was encountered; call hjfsess to find out 
the reason for failure 
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NAME 

hjfndlen — find field length 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

The hjndlen functions returns the length of a target field in the current con- 
nected presentation space. This function can be used to find both protected 
or unprotected fields in a field-formatted presentation space, i.e., a host 
presentation space. 

Calling arguments: 

■ func points to the symbolic H_FNDLEN 

■ data points to a two-character calling data string containing: 

two blanks, T " or "t ": 

this field 

"P " or "p ": the previous protected or unprotected field 

"N " or "n ": the next protected or unprotected field 

"NP" or "np": the next protected field 

"NU" or "nu": the next unprotected field 

"PP" or "pp": the previous protected field 

"PU" or "pu": the previous unprotected field 

■ length is not applicable to hjndlen (2 is implied) 

■ position points to the position within the presentation space where 
the hjndlen function will start 

SEE ALSO 

h_qsys(3X). 

NOTES 

hjndlen returns the number of characters contained in the returned data 
string, including all characters from the beginning of the target field up to 
either the character preceding the next attribute byte, or the end of the 
presentation space. 

RETURN VALUES 

hjndlen returns two arguments: 

■ the first argument is the length of the requested field, not including the 
attribute byte. This value is placed at the location pointed to by the 
length calling parameter. 
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the second argument is a return code, defined in the <xhllapi.h> header 
file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the 
hjndlen call. 

The return code for hjndlen will have one of these values: 
HE_SUCGESS: hjndlen was successful 

HEJLNVAL: your programmed operator was not connected to the 
desired presentation space 

HEJPARM: a parameter error was encountered 

HE POS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 

HE NOFIELD: no such field was found 
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NAME 

hjfndpos — find field position 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

hjndpos returns the beginning position of a target field in the current con- 
nected presentation space. This function can be used to find both protected 
or unprotected fields in a field-formatted host presentation space. 

Calling arguments: 

■ func points to the symbolic H_FNDPOS 

■ data points to a two-character data string containing: 

two blanks, "T ", or "t ": 

this field 

"P " or "p ": the previous protected or unprotected field 

"N " or "n ": the next protected or unprotected field 

"np""NP" or : the next protected field 

"nu""NU" or : the next unprotected field 

"ppxnpp" Qj. . fj^g previous protected field 

"pu""PU" or : the previous unprotected field 

■ length is not applicable to hjndpos (2 is implied) 

■ position points to the position within the field, relative to the origin 
of the presentation space, at which hjndpos will start 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

hjndpos returns two arguments: 

■ the first argument is the the position of the requested field, relative 
to the origin of the presentation space; the origin of the presentation 
space is defined to be the first position after the attribute byte. This 
value is placed in the location pointed to by the length calling param- 
eter. This value is placed at the location pointed to by the length cal- 
ling parameter. 

■ the second argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the hjndpos call. 
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The return code for h_fndpos will have one of these values: 
HE_SUCCESS: hjndpos was successful 

HE_INVAL: your programmed operator was not connected to a 
valid presentation space 

HE_PARM: a parameter error was encountered 

HEJPOS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the hjjsys 
function to find out the reason for failure 
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NAME 

h_getkey — get key 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 

struct getjcey *data; 
int *length; 
, int "^position; 

DESCRIPTION 

Your HLLAPI application program can retrieve keystrokes from sessions 
specified by the h_startkey function call and process them by using h_getkey. 
Keystrokes entered by the terminal user arrive asynchronously, and are 
queued in the keystroke buffer that you provided in your application program 
with h_startkey. 

You can use h_sendkey to the original keystrokes, and any others that your 
application program needs to pass to the target presentation space. 

The CapsLock key has the same effect as the host shift lock key; i.e., pressing 
CapsLock will produce the upper case of all keys, not just of the alphabetic 
keys. 

After the terminal user returns control to your HLLAPI application program, 
repeated calls to the h_getkey function will empty out the buffer of previously 
stored keystrokes. 

Calling arguments: 

■ func points to the symbolic H GETKEY 

■ data points to a structure of type getjcey, defined in the <xhllapi.h> 
header file as shown below: 

typedef struct { 

char gk_psid; /* Presentation Space ID */ 
char gk_option; /* Option code character «/ 
char gk_buf f er [4] ; 

} get_key; 

The members of this structure must all be specified in the calling 
function. They describe the following: 

gk_psid: presentation space short name 

gkjDption: option code character position 

gk_buffei[4]: 4 byte address of the buffer space that will be used 
internally, allocated with h_stman's "Get Storage" 
option. 

■ length and position are not applicable to h_getkey 
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SEE ALSO 

h_qsys(3X), h_sendkey(3X), h_setparms(3X), h_startkey(3X). 

RETURN VALUES 

h_getkey returns two arguments: 

■ the first argument is the structure of type get key mentioned previ- 
ously, describing the following information: 

gk_psid: presentation space short name 

gkjoption: an option code: "A" for ASCII returned (the sym- 
bolic name is GK ASCII); "M" for keystroke 
mnemonic (the symbolic name is GK MNEM); or S 
for special shift (Alt/Ctrl) returned with other data 
(the symbolic name is GK_SHIFT) 

gk_buffei{4]: the 4 bytes of buffer space that will be used inter- 
nally for enqueuing and dequeuing keystrokes; 
bytes 3 and 4 contain ASCII plus X'OO', or @ or 
ESC = n character plus keystroke mnemonic; bytes 
5 and 6 may be similar to bytes 3 and 4, or may be 
set to 0 

This information is placed at the location pointed to by the data calling 
argument. 

■ the second argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the h_getkey call. 

The return code for h_getkey will have one of these values: 

HE_SUCCESS: h_getkey was successful 

HE_INVAL: an invalid presentation space was specified 

HEJNHBT: you specified the "AID only" option under the 
h_startkey function call, and non-AID keys are inhi- 
bited by this session type when HLLAPI tries to 
write invalid keys to the presentation space 

HEJPROC: no prior h_startkey was called for this presentation 
space 

HEJSYSERR: a system error was encountered, call the hjjsys 
function to find out the reason for failure 

HE_NOKEYS: the keystrokes requested are not available on the 
input queue 
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NAME 

h_invoke — invoke UNIX System 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

The hjnvoke function call allows your application program (parent applica- 
tion) to invoke a UNIX System program or command(s). The calling data 
string parameter contains the entire UNIX System command line. Once the 
process is complete, control is returned to your application program and the 
resulting data, if any, is placed into the application program portion following 
the hjnvoke function call. 

Calling arguments: 



■ func points to the symbolic HJNVOKE 

■ data points to the string containing the command line for the UNIX 
command(s) or program 

■ length points to the length of the location pointed to by data 

■ position is not applicable to hjnvoke 



h_qsys(3X). 
RETURN VALUES 

hjnvoke returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the hjnvoke 



SEE ALSO 



call. 



The return code for h invoke will have one of these values: 



HE NOENT: 



HE FNUM: 



an invalid function number was specified 
file not found 



HE ACCESS: 



access denied 



HE ENV: 



HE MEM: 



insufficient memory 
invalid environment 



HE FORM: 



invalid format 
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NAME 

h_pause — pause 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char "^data; 
int ^length; 
int ^position; 

DESCRIPTION 

h_pause waits for a specified amount of time, and should be used in place of 
"timing loops" to wait for an event to occur. A host event may end a h_pause, 
if a prior call was made to h_strthost. 

hjjause should not be used for: 

• tasks with long durations 

• timing out tasks until system response time is better (4:00am, for 
example), and then begin an event 

• applications that require a high-resolution timer; use an alternate tim- 
ing method, since the interval created by h_pause is approximate 

When your application program calls h_pause, the length of the pause is 
affected by the FPAUSE and IPAUSE parameters in h_setparms. You must use 
hjihost to obtain information on the type of update (presentation space and /or 
OIA) and the host, once a host event satisfies a pause, before the next h_pause. 
If your application program uses the IPAUSE option, the pending event will 
continue to satisfy a hjjause until hjfhost returns. 

Calling arguments: 

■ func points to the symbolic H_PAUSE 

■ length points to the pause duration in half-second increments; a prac- 
tical maximum value is 7200 

■ data and position are not applicable to hjjause 

SEE ALSO 

h_qhost(3X), h_qsys(3X), h_setparms(3X). 
RETURN VALUES 

hjjause returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the hjjause 
call. 

The return code for hjjause will have one of these values: 
HE_SUCCESS: the pause duration has expired 

HEJSYSERR: a system error was encountered; use hjjsys to find out 
the reason for failure 



6/88 



1 



H_PAUSE(3X) (AT&T 3270 Emulator+ HLLAPI) H_PAUSE(3X) 

HE_UPDATE: a host session presentation space or OIA has been 
updated; use hjjhost for more information 
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NAME 

hjpostint — post intercept status 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func/ data, length, position) 
int *£unc; 

struct postjntercept *data; 
int ^length; 
int "^position; 

DESCRIPTION 

hjjostint informs the 3270 PC Control Program that a keystroke obtained 
using h_getkey was accepted. 

Your HLLAPI application program does not run at the same time that the ter- 
minal user enters keystrokes, and therefore, this function cannot reject any of 
the keystrokes before they go to the host. However, you can issue the 
hjfostint function call, and the return code will be set to HEJSUCCESS if no 
error conditions are present. 

Calling arguments: 

■ func points to the symbolic H_POSTlNT. 

■ data points to a structure of type post_intercept, defined in the 
<xhllapi.h> header file as follows: 

typedef struct { 

char pi_psid; /* Presentation Space ID */ 
char pi_option; /* Option code */ 

} post_intercept ; 

The members of post_intercept describe the following information: 

pi_psid: short name of the presentation space 

pijoption: "A" for accepted keystroke (the symbolic name is 
PI_ACCEPT), or a "R" for rejected keystroke (the 
symbolic name is PIJREJECT) 

■ length and position are not applicable to hjfostint 

SEE ALSO 

h_getkey(3X), h_qsys(3X). 

RETURN VALUES 

h_postint returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the hjjostint 
call. 

The return code for h_postint will have one of these values: 
HEJSUCCESS: h_postint was successful 
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HEJNVAL: 

HE_PARM: 
HE_PROC: 

HE_SYSERR: 
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an invalid presentation space was specified, one that was 
not connected, configured, or that was labeled with an 
invalid name 

an invalid session option was specified 

no prior h_startkey was called for this presentation space 
ID 

a system error was encountered; use hjjsys to find out 
the reason for failure 
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NAME 

h qattr — query field attribute 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int "^func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

hjjattr returns the attribute byte of the field containing the presentation space 
position in the current connected presentation space, ignoring extended attri- 
bute bytes (EABs). 

Calling arguments: 

■ func points to the symbolic HjQATTR 

■ data and length are not applicable to hjqattr 

■ position points to the position in the current connected presentation 
space (1 through 1920) 

SEE ALSO 

h_qsys(3X). 

NOTES 

Attribute byte values must be greater than X'CO'. 

RETURN VALUES 

hjiattr returns two arguments: 

■ the first argument is the attribute value of the field containing the 
presentation space position in the current connected presentation 
space, or 0 if the screen is iinformatted. This argument is placed at 
the location pointed to by the length calling parameter. 

■ the second argument is a returned code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the h_qattr call. 

The return code for hjjattr will have one of these values: 
HE_SUCCESS: hjiattr was successful 

HEJLNVAL: your programmed operator was not connected to a 
host 

HEJPOS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the h_qsys 
function to find out the reason for failure 
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NAME 

h_qcur — query cursor location 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func/ data, length, position) 
int *func; 
char "^data; 
int ^length; 
int ^position; 

DESCRIPTION 

The hjjcur function shows the position of the cursor in the current connected 
presentation space. The position of the cursor will be returned as follows: 

• if you specified OLDRET with h_setparms, the cursor position will be 
placed at the location pointed to by the position calling argument 

• if you specified NEWRET with h_setparms, the cursor position will be 
placed at the location pointed to by the length calling argument 

You must be connected to the desired presentation space before you can call 
hjicur. 

Calling arguments: 

■ func points to the symbolic HjQCUR 

■ data, length, and position are not applicable to h_qcur. However, you 
must pass pointers to these locations as arguments to hjjcur. 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

RETURN VALUES 

h_qcur returns two arguments: 

■ the first argument is the cursor position. If you specified OLDRET 
with h_setpamis, this argument is placed at the location pointed to by 
the position calling argument. If you specified NEWRET with 
h_setparms, the cursor position is placed at the location pointed to by 
the length calling argument. 

■ the second argument is a return code, defined in the <xhllapi.h> 
header file. If you specified OLDRET with h_setparms, the return code 
is returned as the function value for the h qcur call. If you specified 
NEWRET with h_setparms, the return code is placed at the location 
pointed to by the position calling argument, and is also returned as 
the function value for the h_qcur call. 

The return code for hjjcur will have one of these values: 

HEJSUCCESS: hjjcur was successful 

HE_INVAL: the desired presentation space was not connected 

HEJSYSERR: a system error was encountered; use h_qsys to find 
out the reason for failure 
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NAME 

h_qhost — query host update 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char "^data; 
int *length; 
int ^position; 

DESCRIPTION 

hjjhost lets the programmed operator determine if the host has updated the 
presentation space and /or the OIA, with real data sent from the host, since 
the last time this request was made. The target presentation space must be 
specified in the data string, but you don't need to be connected to a given 
host presentation space to check for updates. Your application program must 
call h_strthost before using h_qhost. 

Calling arguments: 

■ func points to the symbolic HjQHOST. 

■ data points to the target presentation space short name. The presen- 
tation space short name is a capital letter from A through Z, and it is 
the first field for the entry in the LUTABLE environment file that 
corresponds to the target presentation space. 

■ length and position are not applicable to hjjhost 

SEE ALSO 

h_qsys(3X), h_strthost(3X). 

RETURN VALUES 

hjjhost returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h qhost 
call. 

The return code for hjjhost will have one of these values: 

HE SUCCESS: no updates have been made since the last call 
HEJNVAL: 

HEJPROC: 

HE_SYSERR: 

HEjOIA: 
HEJPRES: 
HE_BOTH: 



an invalid presentation space was specified, one that was 
labeled with an invalid name 

no prior h_strthost function was called for this presenta- 
tion space ID 

a system error was encountered; use hjfsys to find out 
the reason for failure 

the OIA was updated 

the presentation space was updated 

both OIA and presentation space were updated 
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NAME 

h_qsess — query sessions 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(£unc, data, length, position) 
int *func; 

struct q_sessions_data *data; 
int *length; 
int ^position; 

DESCRIPTION 

hjjsess returns the session short name, long name, type, and the presentation 
space size for as many presentation spaces as the size of the data calling argu- 
ment can accommodate. This size is specified by the length calling argument. 

Calling arguments: 

■ func points to the symbolic HjQSESS. 

■ data points to a structure of type q_session_data. This structure is 
defined in the Kxhllapi.h header file as follows: 

/« Query Sessions data string */ 

typedef struct { 

char qe_psid; /* 

/* 

char qe_lname[LONG NAME]; /* 

" /* 

char qe_stype; /* 

short qe_size; /* 
} q_sessions_data ; 



Short name */ 

of session */ 
Long name */ 

of session »/ 
Session Type »/ 
PS Size */ 



■ length points to the length of the location pointed to by data. 

■ position is not applicable to hjjsess. 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

hjisess returns two arguments: 

■ the first argument points to a data string structure of type 
q_session_data that contains the session short name, long name, type 
(host) and the presentation space size. This information is placed at 
the location pointed to by the data calling parameter. 

■ the second argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the hj\sess call. 
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The return code for hjjsess will have one of these values: 
HEJSUCCESS: hjjsess was successful 

HEJPARM: an improper string size was specified; the string is 
too small, and the ability to verify the string size is 
language dependent (as with other functions) 

HE_SYSERR: a system error was encountered 
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NAME 

h qstatus — query session status 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 

struct q_status_data *data; 
int ^length; 
int ^position; 

DESCRIPTION 

hjjstatus provides your application program with session-specific information. 
The you need to specify the session short name in the calling data parameter, 
and the requested session information will be returned in the structure 
pointed to by data. 

The session information provided is the session long name, the session type 
('H', for HOST only), the session characteristics, whether the session has base 
attributes or extended attributes, whether the session supports programmed 
symbols, and if your application program is a well-bahaved one (through PIF 
status information). 

Calling arguments: 

■ func points to the symbolic H_QSTATUS. 

■ data points to a structure of type qjstatusjdata, defined in the 
<xhllapi.h> header file as follows: 

/* Query Session Status data string */ 

typedef struct { 



char qt_psid; 


/* 


Short name */ 


char qt_lname [L0N6_NAME] ; 


/» 


Long name */ 


char qt_stype; 


/♦ 


Session type */ 


char qt_schars; 


/» 


Session ■»/ 




/* 


Characteristics 


short qt_rows; 


/* 


Rows in presen- */ 




/* 


tation space */ 


short qt_cols; 


/* 


Columns in PS */ 


char qt_pif Stat [ 2 ] ; 


/* 


PIF Status »/ 


char qt_resefved; 


/« 


Reserved */ 



} q_status_data ; 

The members of the qjstatusjdata structure describe the following 
information: 

qt_psid: presentation space short name 

qt_lname: presentation space long name 

qtjstype: session type ('H' only) 
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qtjschars: sessions characteristics byte: 

SC_EAB: the session has extended attributes 

SC PSS: the session supports programmed symbols 

qtjrows: rows in the presentation space 

qtjcols: columns in the presentation space 

qt_pifstat: PIF status 

qt_reserved: reserved 

You must specifiy the qt_psid and qt_lname members of this structure. 
The remaining members are returned by the hjistatus function call. 

■ length points to the length of the location pointed to by data. 

■ position is not applicable to hjjstatus. 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

hjjstatus returns two arguments: 

■ the first argument points to the structure of type q_status_data men- 
tioned above/ and is placed at the location pointed to by the data cal- 
ling parameter. 

D the second argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the hjjstatus call. 

The return code for hjjstatus will have one of these values: 

HE_SUCCESS: hjjstatus was successful 

HE_INVAL: the requested session was invalid 

HEJSYSERR: a system error was encountered; call the hjjsys 
function to find out the reason for failure 
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NAME 

h_qsys — query system 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 

struct q_system_data ""data; 
int *length; 
int *position; 

DESCRIPTION 

Your HLLAPI application program can use hjjsys to determine the level of 
3270 PC Control Program support, and other system related values, hjjsys 
returns a string with the appropriate system data; the AT&T Tier 4 Support 
group can use this information to help you determine the problem, after you 
received an HE_SYSERR return code (a system error was encountered). 

You should include a return code check in your HLLAPI application program, 
as a prerequisite for continuing the program. If the return code is 
HEJSYSERR (system error), your application program should call a subroutine 
that calls hjjsys, and extracts extended error code information to help the 
AT&T Tier 4 Support group determine the cause of the system error. 

Calling arguments: 

■ func points to the symbolic HjQSYS. 

B data points to a structure of type q_system_data, defined in the 

<xhllapi.h> header file as follows: 

/* Query System data string */ 



typedef struct { 








char 


sy_vernum; 


/* 


HLLAPI Version Number 


*/ 


char 


sy_levnum[ 2 ] ; 


/* 


HLLAPI Level Number */ 


char 


sy_date [ 6 ] ; 


/* 


HLLAPI Date ( MMDDY Y ) 


*/ 


char 


sy_liinver ; 


/* 


LIM Version */ 




char 


sy_limlev[ 2 ] ; 


/♦ 


LIM Level */ 




char 


sy_hwbase ; 


/* 


Hardware Base «/ 




char 


sy_cptype ; 


/* 


Control Program Type 


«/ 


char 


sy_cplevel ; 


/* 


Control Program Level 


*/ 


char 


sy_resv1 ; 


/» 


Reserved */ 




char 


sy_resv2 [ 2 ] ; 


/* 


Reserved »/ 




char 


sy_psid; 


/* 


Session Short Name */ 




char 


sy_exterr 1 [ 4 ] ; 


/* 


Extended Error Code 1 


*/ 


char 


sy_exterr2 [ 4 ] ; 


/* 


Extended Error Code 2 


«/ 


char 


sy_resv[ 8 ] ; 


/* 


Reserved */ 




} q_system 


_data ; 









The members of qjsystem+data describe the following information: 
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sy_vernum: 

sy_levnuin[2]: 

sy_date[6]: 

sy_limver: 

sy_Iimlev[2]: 

sy_hwbase: 

syjcptype: 

syjcplevel: 

syjresvl: 

sy_resv2[2]: 

sy_psid: 

sy_exterrl{4]: 



sy_exterr2[4]: 
sy_resv(8]: 



AT&T 3270 Emulator+ HLLAPI version number 

AT&T 3270 Emulator+ HLLAPI level number 

AT&T 3270 Emulator+ HLLAPI date (month, date, 
and year for service purposes only) 

LIM version number 

LIM level number 

hardware base 

3270 PC Control Program type 
3270 PC Control Program level 
reserved 
reserved 

presentation space short name 

Extended Error Code 1; this is a printable ASCII 
string representing a hex word giving the HLLAPI 
component ID and system error number for that 
function 

Extended Error Code 2; this is a printable ASCII 
string representing a fault symptom code for the 
last internal system error 

reserved 



You do not need to provide any of the above information for data. 

■ length and position are not applicable to hjjsys. 

RETURN VALUES 

h_sys returns two arguments: 

■ the first argument points to the structure of type q_system_data 
described above, and is placed at the location pointed by the data cal- 
ling parameter. 

■ the second argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the hjfsysfl call. 

The return code for hjfsys will have one of these values: 

HE_SUCCESS: hjjsys was successful; data string was returned 

HEJPARM: improper string size (string too small), and the 
ability to verify the string size is language depen- 



HE SYSERR: 



dent 

a system error was encountered 
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NAME 

hjrecv — receive file 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char "^data; 
int *length; 
int ^position; 

DESCRIPTION 

h_recv requests that a file be sent from a host session to the AT&T 3B com- 
puter where HLLAPI is running. 

To receive a file from a host session, you must be logged on to TSO or CMS, 
and have received the ready message on your screen. For TSO, the ready mes- 
sage is "READY", and for CMS it is "R;". 

The TIMEOUT parameter under h_setparms is used by this function. 

Calling arguments for TSO: 

■ func points to the symbolic H_RECV 

■ data points to the file transfer command string. This command string 
has the following format: 

filejtdme h:data_set_name(memberjtame) I password ASCII CRLF 
APPEND 

fUejiame is the name of the file containing the received data. 

h is the short name of the host presentation space that the 
transfer will take place on. It need not be present if only one 
host session is defined in the LUTABLE. If it is present, it 
must be followed by a colon (:). 

data_set_name is the name of the host data set that the file you 
want to transfer is on. If it is a fully qualified name, enclose 
it in single quotes. 

member jiame is the member of a Partitioned Data Set (PDS) 
you wish to receive. If the member name is present, it must 
be enclosed in parenthesis and data_set_name must be the 
name of the PDS. If the member jiame is also part of a fully 
qualified data_set_name both names must be enclosed in single 
quotes (' 

password is the password required to access the host data set. 
If present, it must be preceded by a slash (/). 

ASCII CRLF indicate to the host ASCII/EBCDIC translation 
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will take place during the transfer and also that logical 
records are separated by the two characters CR and LF. Since 
UNIX stores files with records that end in NL, CRLF will be 
automatically translated to NL. These parameters should be 
present if you are receiving text files from the host; they 
should appear separated by a blank, and in the order shown. 
Binary files should not be transferred using this parameter. 

APPEND is an optional parameter that specifies that received 
data is to be added to the end of the local file. If the parame- 
ter is not present, a new file will be created or an existing file 
of the same name will be overwritten. 

■ length points to the length of the location pointed to by data 

■ position is not applicable to hjreco 

Calling arguments for CMS: 

The calling arguments for CMS are the same as for TSO, except for the com- 
mand string pointed to by the data argument. This command string has the 

following format: 

filejiame h:fn ft fm (ASCII CRLF APPEND) 

file_name is the name of the file containing the received data. 

h is the short name of the host presentation space that the transfer will 
take place on. It need not be present if only one host session is defined 
in the LUTABLE. If it is present, it must be followed by a colon (:). 

fn ft fm is the file name, file type, and file mode of the receive file on 
CMS. The file name is required, while the file type and file mode are 
optional. 

ASCII CRLF indicate to the host ASCII EBCDIC translation will take 
place during the transfer and also that logical records are separated by 
the tv/o characters CR and LF. Since UNIX stores files with records that 
end in NL, CRLF will be automatically translated to NL. This parameter 
should be present if you are receiving text files from the host; binary 
files should not be transferred using this parameter. 

APPEND is an optional parameter that specifies that received data is to 
be added to the end of the local file. If the parameter is not present, a 
new file will be created or an existing file of the same name will be 
overwritten. 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

RETURN VALUES 

hjrecv returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
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calling argument, and is also returned as the function value for the hjrecv call. 

The return code for hjecv will have one of these values: 

HEJPARM: parameter error - you have specified a data string length 
that is too long, and the file transfer was unsuccessful 

HE_XCOMPL: file transfer complete 

HE_XCOMPLSEG: 

file transfer complete with records segmented 

HE SYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 



HE. 


_FNUM: 


invalid function number 


HE. 


_NOENT: 


file not found 


HE. 


ACCESS: 


access denied 


HE. 


_MEM: 


insufficient memory 


HE. 


_ENV: 


invalid environment 


HE. 


_FORM: 


invalid format 
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NAME 

h_redir — UNIX System redirect 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char *data; 
int ^length; 
int "^position; 

DESCRIPTION 

hjedir allows the parent application program to do anything that you could 
do from the shell prompt '$'. Once this process is complete, control is 
returned to the parent application. 

Calling arguments: 

■ func points to the symbolic HJREDIR 

■ data points to the string containing the UNIX System command line 

■ length points to the length of the data string parameter 

■ position is not applicable to hjedir 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

hjredir returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the hjedir 
call. 

The return code for hjedir will have one of these values: 

HE_FNUM: an invalid function number was specified 

HEJSrOENT: file not found 

HE_ACCESS: access denied 

HE_MEM: insufficient memory 

HE_ENV: invalid environment 

HE FORM: invalid format 
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NAME 

h_rel — release 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

h_rel unlocks a presentation space that was reserved using hjesv; the target 
presentation space is the current connected presentation space. 

Calling arguments: 

■ func points to the symbolic H_REL 

■ data, length, and position are not applicable to hjel 

SEE ALSO 

h_resv(3X), h_qsys(3X). 

NOTES 

A presentation space can be controlled, in a mutually exclusive way, by 
either the terminal user or the HLLAPI application program. Therefore, hjel 
has no real functionality in the AT&T 3270 Emulator+ HLLAPI implementa- 
tion, and it has been included for compatibility with the IBM 3270 HLLAPI 
product. 

RETURN VALUES 

hjrel returns one argument: a return code, defined in the <xhllapi.h> header 
file. The return code is placed at the location pointed to by the position calling 
argument, and is also returned as the function value for the hj'el call. 

The return code for h_rel will have one of these values: 

HEJSUCCESS: /t_re/ was successful 

HEJINVAL: you HLLAPI application program is not connected to a 
valid presentation space 

HEJSYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 
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NAME 

h_reset — reset system 

SYNOPSIS 

#iiiclude <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int * length; 
int "^position; 

DESCRIPTION 

hjreset reinitializes the HLLAPI library, and resets the session parameter 
options to their defaults. This function releases any reserved sessions, and 
disconnects all connected presentation spaces. 

You can use hjeset during initialization, or at the end of the program to reset 
the system to a known initial condition. 

Calling arguments: 

■ func points to the symbolic H_RESET 

■ data, length, and position are not applicable to hjeset 

SEE ALSO 

h_qsys(3X), h_setparms(3X), h_stman(3X). 

NOTES 

hjeset does not free up blocks of storage that were allocated with h_stman; 
use the "Free All Storage" option under h_stman for this purpose. 

RETURN VALUES 

hllapi returns one argument: a return code, defined in the <xhllapi.h> header 
file. The return code is placed at the location pointed to by the position calling 
argument, and is also returned as the function value for the hjeset call. 

The return code for hjeset will have one of these values: 

HE_SUCCESS: hjeset was successful 

HEjSYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 
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NAME 

hjresv — reserve 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

hjresv locks the current connected presentation space to prevent input from 
the terminal operator. You may need to prevent the user from gaining access 
to the host session where your HLLAPI application program is sending tran- 
sactions, until the application program is done. 

Calling arguments: 

■ func points to the symbolic HJRESV 

■ data, length, and position are not applicable to h_resv 

SEE ALSO 

h_qsys(3X). 

NOTES 

A presentation space can be controlled, in a mutually exclusive way, by 
either the terminal user or the HLLAPI application program. Therefore, 
hjesv has no real functionality in the AT&T 3270 Emulator+ HLLAPI imple- 
mentation, and it has been included for compatibility with the IBM 3270 
HLLAPI product. 

RETURN VALUES 

hjesv returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_resv call. 

The return code for hjresv will have one of these values: 

HE_INVAL: your HLLAPI program is not connected to a valid 
presentation space 

HEJINHBT: hjeso failed because the presentation space was inhi- 
bited 

HEJSYSERR: a system error was encountered; hjfsys to find out the 
reason for failure 
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NAME 

h search — search presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *£unc; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

The h_search function allows your HLLAPI program to search for a particular 
string within the current connected presentation space, h jearch normally 
checks the entire presentation space. 

h_search scans the presentation space for the specified string, and if you 
specified OLDRET: 

■ the return code is set to the beginning location of the string in the 
presentation space, if the string is found. This location is based on 
the layout where the upper left corner is location 1 (row 1, column 
1), and the lower right corner is: 

□ 1920 for Model 2s 

□ 3564 for Model 5s 

■ if the string is not found, the return code is set to 0. 
If you specified NEWRET with h_setparms: 

■ the returning length is set to the beginning location of the string 
in the presentation space, if the string is found. This location fol- 
lows the same layout as described above for OLDRET 

■ the returning lenght is set to 0 is the string is not found 

You can use the h_search function to determine when a specific 3270 presenta- 
tion space is available. h_search allows you to check for specific prompt mes- 
sages before continuing, if your programmed operator is expecting a specific 
prompt or message before sending data. Your program can then call the 
h_pause or hjfhost function calls and continue to call h_search until it receives a 
non-zero return code. 

The parameters under h_setparms that relate directly to search functions are 
listed below; an asterisk {*) means that this is the default option: 

SRCHALL *: the search function will scan the entire presentation 
space. 

SRCHFROM: the search function will start from the specified begin- 
ning position. 

SRCHFRWD *: the search function will take place in an ascending 
direction. 
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SRCHBKWD: the search function will tcike place in a descending 
direction. If the first character of the requested string 
starts within the specified search bounds, the search will 
be satisfied. 

If you are looking for a string that may occur multiple times within the 
presentation space, you can use h_setpamis to specify SRCHFROM. Once you 
specify a search starting position, the function looks for the named string 
from that position through the end of the presentation space. 

Calling arguments: 

■ func points to the symbolic H_SEARCH 

■ data points to the string to be searched 

■ length points to the length of data 

■ position points to the address where the search will begin (not used 
with the SRCHALL option under h_setparms) 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

NOTES 

You can also use hjetparms to specify SRCHBKWD. In this mode, the search 
function locates the last time the string occurs. 

RETURN VALUES 

h_search returns two arguments: 

■ the first argument is the starting position of the searched string, and it is 
placed at the position pointed to by the length calling parameter. If you 
specified NEWRET with h_setparms, then the value for this argument will 
be: 

length " 0: the string was not found 

length > 0: the string was found at the presentation space position, 
shown in length 

■ the second argument is a return code, defined in the <xhllapi.h> header 
file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the 
h_search call. 

If you specified OLDRET with h_setparms, then the return code will be 
will be 

— 0: meaning that the string was not found 

> 0: meaning that the string was found at the presenta- 

tion space position shown in position 

If you specified NEWRET with h_setparms, and length > 0, then the return 
code will be: 

HEJSUCCESS: hjearch was successful 
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HE_INVAL: the specified presentation space was not connected 

HE_PARM: an error was made in specifying parameters 

HE_POS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the hjjsys 
function to find out the reason for failure 

HE_NOFIELD: the search string was not found 
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NAME 

h_send — send file 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func/ data, length, position) 
int *func; 
char "^data; 
int ^length; 
int *position; 

DESCRIPTION 

h_send is used to send a file from the AT&T 3B computer, where HLLAPI is 
running, to a TSO or CMS host session. 

To send a file to the host session, you must be logged on to TSO or CMS, and 
have received the ready message on your screen. For TSO, the ready message 
is "READY", and for CMS it is "R;". 

The TIMEOUT parameter under h_setparms is used by this function. 

Calling arguments for TSO: 

■ func points to the symbolic H_SEND 

■ data points to the command line for the file that you want to send to 
the host This command line must contain the following information: 

filejiame h:data_set_name(member_name)/ password ASCII CRLF 
APPEND LRECL(n) BLKSIZE(n) RECFM(x) SPACE(nl,n2) units 

filejiame is the name of the file that contains the data to be 
transmitted. 

h is the short name of the host presentation space that the transfer 
will take place on. It need not be present if only one host session 
is defined in the LUTABLE. If it is present, it must be followed by 
a colon. 

data_set_name is the host data set you wish the transferred file to 
reside. If it is a fully qualified name, enclose it in single quotes. 

member jiame is the member of a Partitioned Data Set (PDS) you 
wish to send to. If meniberjtame is present, it must be enclosed in 
parenthesis and data_set_name must be the name of the PDS. If the 
memberjiame is also part of a fully qualified data_set_name, both 
names must be enclosed in single quotes. 

password is the password required to access the host data set. If 
present, it must be preceded by a slash (/). 

ASCII CRLF indicate to the host ASCII /EBCDIC translation will 
take place during the transfer and also that logical records are 
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separated by the two characters CR and LF. Since UNIX stores files 
with records that end in NL, NL will be automatically translated to 
CRLF. These parameters should be present if you are receiving text 
files from the host; they should appear separated by a blank, and 
in the order shown. Binary files should not be transferred using 
this parameter. 

APPEND is an optional parameter that specifies that transmitted 
data is to be added to the end of the host file. If the parameter is 
not present, a new file will be created or an existing file of the 
same name will be overwritten. 

LRECL(n) if present indicates the record length of the TSO file, n 
may be from 1 to 132, with a default of 80 if this parameter is not 
present. This parameter may not be included if the member param- 
eter is specified. 

BLKSIZE(n) is an optional parameter indicating the block size of 
the new TSO data set. If the member parameter is present this 
parameter may not be used. The default for this parameter is the 
same as the logical record length (LRECL). 

RECFM(x) is optional indicating the record format of the new TSO 
data set. x may be v, f or u for variable, fixed or undefined. If the 
CRLF parameter was specified and this parameter was not, the data 
set will be created for variable length records otherwise the records 
are assumed to be fixed length. This parameter should not be 
included if the member parameter was specified. . 

SPACE(nl,n2) units is an optional parameter indicating the amount 
of space to be allocated for the new data set. nl indicates the size 
of the initial allocation and n2 the amount of all subsequent addi- 
tions to the data set. units may be anyone of BLOCKS, TRACKS or 
CYLINDERS. If this parameter is omitted, a new data set will only 
be allocated one block. If the member parameter was used, this 
parameter should not be present. 

■ length points to the length of the string pointed to by data 

■ position is not applicable to h_send 

Calling arguments for CMS: 

The calling arguments for CMS are the same as for TSO, except for the com- 
mand string pointed to by the data argument. This command string has the 
following format: 

filejtame h:fn ft fm (ASCII CRLF APPEND LRECL(n) RECFM(x)) 

filejiame is the name of the file that contains the data to be transmitted. 
h is the short name of the host presentation space that the transfer will 
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take place on. It need not be present if only one host session is defined 
in the LUTABLE. If it is present, it must be followed by a colon (:). 

fn ft fm is the file name, file type, and file mode of the target file on 
CMS. The file name and file type is required. The file mode is optional 
and will default to your A disk. 

ASCII CRLF indicate to the host ASCII /EBCDIC translation will take 
place during the transfer and also that logical records are separated by 
the two characters CR and LF. Since UNIX stores files with records that 
end in NL, NL will be automatically translated to CRLF, These parame- 
ters should be present if you are receiving text files from the host; they 
should appear separated by a blank, and in the order shown. Binary 
files shoiild not be transferred using this parameter. 

APPEND is an optional parameter that specifies that transmitted data is 
to be added to the end of the host file. If the parameter is not present, a 
new file will be created or an existing file of the same name will be 
overwritten. 

LRECL(n) if present indicates the record length of the CMS file, n may 
be from 1 to 132, with a default of 80 if this parameter is not present. 

RECFM(x) is optional indicating the record format of the new CMS data 
set. X may be v or f for variable, fixed. If the CRLF parameter was 
specified and this parameter was not the data set will be created for vari- 
able length records otherwise the records are assumed to be fixed length. 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

RETURN VALUES 

h_send returns one argument: a return code, defined in the <xhllapi.h> 
header file. The rettirn code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_send 
call. 

The return code for h_send will have one of these values; 

HEJPARM: parameter error - you have specified a data string 

length that is too long, and the file transfer was 
unsuccessful 

file transfer complete 

file transfer complete with records segmented 

a system error was encountered; call the hjjsys 
function to find out the reason for failure 

HE_FNUM: invalid function number 

HE NOENT: file not found 



HEJCCOMPL: 

HEJCCOMPLSEG: 

HEJSYSERR: 
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HE_ACCESS: 
HE_MEM: 
HE_ENV: 
HE_FORM: 



access denied 
insufficient memory 
invalid environment 
invalid format 
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NAME 

h_sendkey — send key 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int ""func; 
char *data; 
int "^length; 
int "^position; 

DESCRIPTION 

h_sendkey sends a string of keystrokes to the current connected presentation 
space. You must use h_connect in your application program before sending 

keystrokes. 

You define the keystrokes that will be sent in the calling data parameter, and 
they will appear to the target session as though they were entered by the ter- 
minal operator. You cannot send keystrokes to a session whose keyboard is 
locked (e.g., when input is inhibited), and your application program must deal 
accordingly with those fields that are protected for input, or that are numeric 
only. 

You can send all attention identifier (AID) keys such as Enter, PAl, etc, but 
keystroke input will no longer be accepted after the first AID character is 
received. The remainder of the input data string will be ignored. 

To send special keystrokes, use the ESC character that you specified with 
h_setparms function call (@ is the default), followed by the keystroke 
mnemonic, in the calling data string: 



Name 


Keystroke 


Name 


Keystroke 


ALT CR 


@A@n 


PFl 


@1 


ATTN 


@A@Q 


PF2 


@2 


Backtab 


@B 


PF3 


@3 


Clear 


@c 


PF4 




Delete 


@D 


PF5 


@5 


Down arrow 


@D 


PF6 


@6 


DUP 


@S@x 


PF7 


@7 


Enter 


@E 


PF8 


@8 


Erase EOF 


@F 


PF9 


@9 


Erase Input 


@A@F 


PFIO 


(ga 


FM 


@S@y 


PFll 


@b 


Home 


@0 


PF12 


@c 


Insert 


@I 


PF13 


@d 


LDUB 


@A@L 


PF14 


@e 


Left arrow 


@L 


PF15 


@f 
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New Line 


@N 


PF16 


@g 


Print 


@A@P 


PF17 


@h 


RDUB 


@A@R 


PF18 


@i 


Right arrow 


@R 


PF19 


@j 


Tab 


@T 


PF20 


@k 


Test 


@A@C 


PF21 


@1 


Up arrow 


@U 


PF22 


@m 


Reset 


@R 


PF23 


@n 


PAl 


@x 


PF24 


@o 


PA2 


@y 


PA3 


@z 



For information regarding the use of the keys listed above, see the AT&T 3270 
Emulator+ User's Guide. 

Calling arguments: 

■ func points to the symbolic H_SENDKEY 

■ data points to the string of keystrokes that you want to send 

■ length points to the length of the string pointed to by data 

■ position is not applicable to h_sendkey 

SEE ALSO 

h_connect(3X), h_qsys(3X), h_setparms(3X). 

NOTES 

A receiving session left in shift lock (CapsLock) state will cause numeric data 
to be sent as alphabetic data. 

RETURN VALUES 

h_sendkey returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_sendkey 
call. 

The return code for h_sendkey will have one of these values: 

the keystrokes were sent, and status is normal. 

yovir HLLAPI program is not connected to a valid ses- 
sion 

an incorrect parameter was passed to HLLAPI 

the 3270 host session was busy; all the keystrokes could 
not be sent 

input to the target session was inhibited or rejected; of 
the keystrokes could not be sent 

a system error was encountered; call h_qsys to find out 
the reason for failure 



HE 


.SUCCESS: 


HE 


JNVAL: 


HE. 


FARM: 


HE. 


_BUSY: 


HE. 


JNHBT: 


HE 


SYSERR: 
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NAME 

h setparms — set session parameters 

SYNOPSIS 

#include <xhllapi.h> 

int hllapKfunc, data, length, position) 
int *£unc; 
char *data; 
int ^length; 
int "'position; 

DESCRIPTION 

h_setpartns lets you change certain default session options in the HLLAPI 
library. These options are described next in terms of the functions that they 
affect, and are presented in mutually exclusive groups; an asterisk (*) follow- 
ing the name of a parameter within each group specifies that this is the 
default option. 

The following parameters affect h_search, hjjcur, and hjfsess: 



Parameter 


Description 


NEWRET * 
OLDRET 


HLLAPI release 3.0 is in use; this release uses the 
standard return codes 

HLLAPI release 1.0 or 2.0 is in use; these versions 
do not use the standard return codes, but allow the 
return code to include the result code 
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These parameters affect all Copy functions: 



H_SETPARMS(3X) 



Parameter 


Description 


ATTRB 
NOATTRB * 


pass back all codes that do not have an ASCII 
equivalent (except EABs) as their original values 

convert all unknown values to blanks 


EAB 

NOEAB * 


pass the presentation space data with extended 
attribute bytes; you will get two characters for 
every one that appears on the screen (remember 
that you must allocate a buffer twice the size of the 
presentation space, e.g., 2x1920 for a Model 2 
screen) 

pass data only (no EABs) 


STRLEN * 
STREOT 


an explicit length will be passed for all strings 

string lengths are not explicitly coded; they end 
with an EOT (End Of Text) character 


EOT=n 


allows you to specify the EOT to show the end of a 
string in STREOT mode. Binary zero is the default. 
You may use any character except a blank after the 
equals sign. 
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The following parameters affect h_connect: 



H_SETPARMS(3X) 



Parameter 


Description 


CONPHYS 
CONLOG * 


do a physical connection; i.e., during an h_connect 

Space, and transfers control to the user at the termi- 
nal to enter data using the keyboard 

do a logical connect with the requested presenta- 
tion space, and do not transfer control or allow the 
user at the terminal to be aware of this connection 
unless the DISPLAY option (below) has been 
specified 


DISPLAY 
NODISPLAY * 


allow the user to view the results of your HLLAPI 
application program during an h_connect function 
call (if you specified the CONLOG option, above) 

do not allow the user at the terminal to view the 
results of your HLLAPI application program execu- 
tion during a h_connect function call (if you 
specified the CONLOG option, above) 


These parameters affect h_sendkey: 


Parameter 


Description 


ESC=-n 


specify the escape character for keystroke mnemon- 
ics (@ is the default); any character is valid except 
a blank 


AUTORESET * 
NORESET 


the application will attempt to reset all inhibited 
conditions by prefixing all strings of keys sent 
using h sendkey with a keyboard reset key sequence 

do not AUTORESET 
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These parameters that affect all Search functions: 
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Parameter 


Description 


SRCHALL * 
SRCHFROM 


the search will scan the entire presentation space 

the search will start from a specified beginning 
position 


SRCHFRWD * 
SRCHBKWD 


the search will be performed in an ascending direc- 
tion, and a search will be satisfied if the first char- 
acter of the requested string starts within the 
bounds specified for the search 

the search will be performed in a descending direc- 
tion, and a search will be satisfied if the first char- 
acter of the requested string starts within the 
bounds specified for the search 



The parameters related to using TRACE to debug your HLLAPI application 
program are: 



Parameter 


Description 


TRON 
TROFF * 


turns TRACE on 

turns TRACE off; the trace function may conflict 
with messages on the screen from languages or 
applications that manage their own displays 
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The following parameters affect the hjvait and h_getkey: 



Parameter 


Description 


TWAIT • 


hjoait will return control to your application pro- 
gram after a pending event completes, if there is 
one; otherwise, hjoait will wait approximately one 
minute before timing out on XCLOCK or XSYSTEM 
and returning control to your application program 


LWATT 


hjoait will wait indefinitely or until XCLOCK or 
XSYSTEM clears, i.e., after an event occurs; this 
option is not recommended since control does not 
return to your application program if there is no 
event pending 


NWAIT 


hjvait checks the status of an event, and returns 
control immediately to your application program 
(no wait) 


The parameters that affect the hjjause function call are: 


Parameter 


Description 


FPAUSE * 


full duration pause 


IPAUSE 


interruptible pause; hjtrthost and a host event will 
satisfy a hjjause 
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The following parameters affect the h_send and h_recv: 



Parameter 


Description 


QUIET 
NOQUIET * 


keeps SEND and RECEIVE and any other messages 
sent to the screen from being displayed and 
HLLAPI will keep track of the message number 
and discard the message; the UNIX System pro- 
vides the capability to redirect I/O, and therefore, 
the use of this parameter may have no effect 

restores message display; the use of this parameter 
may have no effect since the UNIX System provides 
the capability to redirect I/O 


TIMEOUT-n 


where "n" is a value from the table below. 
TIMEOUT messages will be displayed every 30 
seconds until the operator presses CTRL+BREAK 
(these messages would not be visible in the QUIET 
mode); TIMEOUT=0 is the standard for operator 
usage of SEND and RECEIVE, and TIMEOUT=n 
causes a one-character specifier from Figure 4-1 to 
tell the HLLAPI library how many 30 second cycles 
(how many messages with INDFTOlO) it should 
accept before issuing a CTRL-f-BREAK 



Character Specifiers Used with the Timeout Option: 



iracter 


Value 


Character 


Value 




(in 30 sec 




(in 30 sec 




cycles) 




cycles) 


1 


0.5 


8 


4.0 


2 


1.0 


9 


4.5 


3 


1.5 


J 


5.0 


4 


2.0 


K 


5.5 


5 


2.5 


L 


6.0 


6 


3.0 


M 


6.5 


7 


3.5 


N 


7.0 
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The parameters that affect the handling of IBM Personal Computer HLLAPI 
unsupported functions are listed below. These functions are: 

■ Define Presentation Space 

■ Switch Presentation Space 

■ Display Cursor 

■ Display Presentation Space 

■ Delete Presentation Space 

■ Get 3270 Aid Key 



Parameter 


Description 


UNSUP_OK 
UNSUPJMG 
UNSUP_VAR • 


returns a return code of "0" (operation successful) 
unconditionally without taking any further actions 

returns a return code of "10" (function not sup- 
ported) unconditionally without doing anything 

returns either a return code of "0" or "10" depend- 
ing on the function 



Calling arguments: 

■ func points to the symbolic H_SETPARMS 

■ data points to a character string that contains the session parameters previ- 
ously described, separated by commas or blanks 

■ length points to the length of the data string (no EOT) 

■ position is not applicable 

SEE ALSO 

h_qsys(3X). 

NOTES 

The parameter EOT— n also affects h_send, hjrecv, hjnvoke, and hjredir. 
ESC=n also affects h_getkey. 
RETURN VALUES 

h_setparms returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_setparms 
call. 
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The return code for h_setparms will have one of these values: 

HE_SUCCESS: the session parameters have been set 

HEJPARM: the length of the parameter list is invalid 

HEJSYSERR: a system error was encountered; call the h_qsys function 
to find out the reason for failure 
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NAME 

hjsrchfld — search field 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func/ data, length, position) 
int *£unc; 
char *data; 
int *length; 
int "^position; 

DESCRIPTION 

h_srchfld searches the last connected presentation space for the occurrence of 
the string specified in the data calling parameter. This function returns the 
decimal position of the string, numbered from the beginning of the presenta- 
tion space, if the target string is found (position 1 is the "row 1, column 1" 
position). h_srchfld can be used to search for either protected or unprotected 
fields, but only in a field-formatted host presentation space. 

The search will not wrap from the bottom of the screen to the top; you can 
use h_setparms to determine whether your searches will search forward or 
backward. 

Calling arguments: 

B func points to the symbolic H_SRCHFLD 

■ data points to the target search string 

■ length points to the length of the location pointed to by data if 
STRLEN (under h_setparms is on), or to a blank if STREOT is on 

■ position points to the position within the presentation space where 
the search will begin 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

NOTES 

If you pass a position that does not coincide with the beginning of a field, the 
search will start at the beginning of the field that contains the presentation 
space position passed. 

RETURN VALUES 

h_srchfld returns two arguments: 

■ the first argument is placed at the location pointed to by the length 
calling parameter, and has one of two values: 

•=< 0: means that the string was not found 

> 0: means that the string was found at the presentation 

space position shown 

■ The second argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the h_srchfld call. 
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The return code for h_srchfld will have one of these values: 
HEJSUCCESS: h_srchfld was successful 

HE_INVAL: your programmed operator was not connected to a 
valid presentation space 

HEJPOS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the hjfsys 
function to find out the reason for failure 

HE_NOFIELD: the search string was not found, or the screen was 
unformatted 
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NAME 

h startkey — start keystroke intercept 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 

struct start_keystroke *data; 
int *length; 
int ^position; 

DESCRIPTION 

h_startkey allows your application program to record keystrokes sent to a ses- 
sion by a terminal operator. The recorded keystrokes may be: 

• received through the h_getkey function call and sent to the same or 
another session with h_sendkey 

• used to trigger some other process 

After you issue a h_startkey function call, you must give explicit control of the 
session to the terminal user. You can accomplish this by issuing an h_connect 
function call, and specifying the CONPHYS option with h_setparms. 

The buffer area that length points to must be large enough to hold all keys- 
trokes entered by the terminal user, until control is returned to your HLLAPI 
application program. If the terminal user enters more keystrokes than this 
buffer will hold, the most recent ones will be truncated. 

The h_stman option "Get Storage" returns a 4-byte address in the calling data 
string parameter that can be concatenated with the first data string bytes for 

h_getkey. 

Calling arguments: 

■ func points to the symbolic H_STARTKEY. 

■ data points to a structure of type startjceystroke, defined in the 
<xhllapi.h> header file as follows: 

typedef struct { 

char sk_psid; /* Presentation Space ID */ 
char sk_option; /« Option Code */ 
char *sk_buffer; 

} start_keystroke ; 

The members of the startjceystroke structure describe the following: 

sk_psid: presentation space short name 

sk option: an option code character: SK_AID, for AID keys- 
trokes only, or SK ALL for all keystrokes 

skjbuffer: address of a buffer space that will be used inter- 
nally for enqueuing and dequeuing of host events; 
allocated with h stman. 
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■ length points to the length of the location pointed to by data. 

■ position is not applicable to h_startkey. 

SEE ALSO 

h_connect(3X), h_getkey(3X), h_postint(3X), h_qsys(3X), h_sendkey(3X), 
h_setparms(3X), h_stman(3X). 

RETURN VALUES 

hjtartkey returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_startkey 
call. 

The return code for h_startkey will have one of these values: 
HE SUCCESS: hjtartkey was successful 
HEJPARM: an invalid option was specified 

HE_BUSY: the execution of the function was inhibited because the 
target presentation space was busy 

HEJSYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 
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NAME 

h_stman — storage manager 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, id, subfunc) 

int *func; 

char "^data; 

int *id; 

int ^subfunc; 

DESCRIPTION 

h_stTnan preallocates blocks of storage for use by certain HLLAPI functions. 
The h_stman subfunctions are: 

■ Get Storage Get Storage allocates a portion of the storage block 

for use by a particular HLLAPI function. The size 
of the allocated storage block will be equal to the 
requested size, plus 5 bytes; you can allocate a 
maximum of 128 blocks of storage. 

■ Free Storage Free Storage frees a block of storage that was previ- 

ously allocated with Get Storage. 

■ Query Free Storage Query Free Storage searches for, and returns, the 

size of the largest available free storage block. 
The size of this block must be larger than 5 bytes 
to be used with Get Storage. 

■ Free All Storage Free All Storage frees all allocated storage blocks, 

and regroups them into a single storage pool. 

Calling arguments: 

■ func points to the symbolic H STMAN 

■ data is not applicable, although it is preallocated to 4 bytes 

■ id points to the size of the requested storage area; the maximum 
storage area is determined by the STSIZE environment variable, 
defined in the LIM .profile 

■ subfunc points to an h_stman subfunction: 

01 Get Storage 

02 Free Storage 

03 Query Free Storage 

04 Free All Storage 

SEE ALSO 

h_qsys(3X). 

NOTES 

A given storage block will remain the size of the original allocation; later 
requests for storage will waste the excess storage in the previously allocated 
block. For example, if a block of 100 bytes was allocated and freed, and later 
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you requested to reallocate the block with 80 bytes, the excess 20 bytes are 
wasted. 

RETURN VALUES 
Get Storage 

h_stman returns three arguments for Get Storage: 

■ the first argument is the storage address, expressed as two binary 
words (4 bytes) in offset segment order. This address is placed at 
the location pointed to by the data calling parameter. 

■ the second argument is the storage block id (0 - 127), and it is 
placed at the location pointed to by the id calling parameter. 

■ the third argument is a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by 
the position calling argument, and is also returned as the function 
value for the h_stman call. 

The return code will have one of these values: 

HE_SUCCESS: the requested storage was allocated 

HEJINVAL: you requested more storage than is available 

HE_SYSERR: a system error was encountered; call the h_qsys 
function to find out the reason for failure 

Free Storage 

h_stman returns one argument for Free Storage: a return code, placed at the 
same locations as the return code for Get Storage. The possible return codes 
are: 

HE_SUCCESS: storage block has been freed 
HEJPARM: the storage block ID was invalid 

HE_SySERR: a system error was encountered; call the hjfsys function 
to find out the reason for failure 

Query Free Storage 

h_stman returns two arguments for Query Free Storage: 

■ the first argument is the size of the largest available block of storage, 
and it is placed at the location pointed to by the length calling parameter. 

■ the second argument is a return code, placed at the same locations as the 
return codes for the previously described subfunctions. The possible 
return codes are: 

HE_SUCCESS: Query Free Storage was successful 

HEJSYSERR: a system error was encountered; call the h_qsys function 
to find out the reason for failure 

Free All Storage 

h_stman returns two arguments for Free All Storage: 

■ the first argument is the size of the largest available block of storage, 
and it is placed at the location pointed to by the length calling parameter. 
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the second argument is a return code, placed at the same location as the 
return codes for the previously described subfunctions. The possible 
return codes for Free All Storage are: 

HEJSUCCESS: Free All Storage was successful 

HEJSYSERR: a system error was encountered; use hj\sys to find out 
the reason for failure 
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NAME 

h stophost — stop host notification 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int "^length; 
int ^position; 

DESCRIPTION 

h_stophost disables the ability of h_qhost to determine if the specified host OIA 
and /or the presentation space have been updated. h_stophost also stops host 
events from the specified host from affecting hjjause. 

Calling arguments: 

■ func points to the symbolic HJSTOPHOST 

■ data points to the presentation space short name 

■ length and position are not applicable 

SEE ALSO 

h_pause(3X), h_qhost(3X), h_qsys(3X), h_setparms(3X). 
RETURN VALUES 

h_stophost returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_stophost 
call. 

The return code for hjtophost will have one of these values: 
HEJSUCCESS: hjtophost was successful 

HE_INVAL: an invalid presentation space was specified, one labeled 
with an invalid name 

HE_PROC: no previous h_stophost was issued 

HEJSYSERR: a system error was encountered; use hjjsys to find out 
the reason for failure 
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NAME 

h stopkey — stop keystroke intercept 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char *data; 
int *length; 
int ^position; 

DESCRIPTION 

hjtopkey ends yoxir application program's ability to intercept keystrokes with 
hjtartkey. 

Calling arguments: 

■ func points to the symbolic H_STOPKEY 

■ data points to the short name of the target presentation space 

■ length and position are not applicable to h_stopkey 

SEE ALSO 

h_qsys(3X). 

RETURN VALUES 

h_stopkey returns one argument: a return code, defined in the <xhllapi.h> 
header file. The retiurn code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_stopkey 
call. 

The return code for h_stopkey will have one of these values: The possible 
return codes are: 

HE_SUCCESS: hjtopkey was successful 

HEJINVAL: an invalid presentation space was specified 

HE_PROC: no prior hjtopkey was called for this presentation space 

HE_SYSERR: a system error was encountered; use h jfsys to find out 
the reason for failure 
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NAME 

h strthost — start host notification 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 

struct host_notify *data; 
int *length; 
int ^position; 

DESCRIPTION 

h_strthost determines if the specified presentation space and /or the specified 
OIA have been updated, and enables the specified presentation space ID to 
end a pause started with h_pause. After using h_strthost, your application pro- 
gram can use hjjhost to determine the specific host event that has occurred. 

If you allocate buffer storage within your HLLAPI application program 
without using h_stman, you must use h_$tophost or h_reset functions before you 
exit HLLAPI. This will avoid storage overlap failure of later programs. 

The "Get Storage" option in h_stman returns a 4-byte address in the data string 
parameter that can be concatenated with the first data string bytes for this 
function. 

Calling arguments: 

■ func points to the symbolic HJSTRTHOST. 

■ data points to a structure of type host_notify, defined in the 
<xhUapi.h header as follows: 

typedef struct { 

char hn_psid; /« Presentation Space ID */ 
char hn_type; /» Update type */ 
char »hn_buffer; 

} host_notify; 



You must provide values for all members of the structure of type 
host_notify/ which describe the following: 

hn_psid: a specific presentation space short name (PSID). 

hnjlype: one of these possibilities: 

the symbolic HN_PRES, asking for notification of 
presentation space update only 
the symbolic HNjOIA, asking for notification of 
OIA Update only 

the symbolic HNJBOTH, asking for notification of 
both presentation space and OIA updates, or 

*hn_buffer: the address of the buffer space that will be used 
internally for enqueuing and dequeuing host 
events (specified with h_stman function call, using 
the "Get Storage" subfunction). 
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■ length points to the length of the host event buffer; this buffer 
should be long enough to store the desired keystrokes. 

■ position is not applicable to h_strthost. 

SEE ALSO 

h_pause(3X), h_qhost(3X), h_qsys(3X), h_reset (3X), h_stman(3X), 
h_stophost(3X). 

RETURN VALUES 

h_strthost returns one argument: a return code, defined in the <xhllapi.h'>^ 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the h_strthost 
call. 

The return code for h_strthost will have one of these values: 

HE_SUCCESS: h_strthost was successful 

HE_INVAL: an invalid presentation space was specified 

HE PARM: an error was made when specifying parameters 

HE_SYSERR: a system error was encountered; use hjjsys to find out 
the reason for failure 
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NAME 

hwait — wait 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int "^func; 
char *data; 
int ^length; 
int *position; 

DESCRIPTION 

hjvait checks the status of the current connected presentation space. If the 
3270 session is waiting on a host response, suggested by XCLOCK or XSYS- 
TEM, hjvait will cause your application program to wait approximately one 
minute to see if the condition clears (if the default option TWAIT is set using 

h_setparms). 

hjvait gives host requests, like those made by h_sendkey, time to complete 
before continuing. This is analagous to an operator waiting for the keyboard 
to unlock before entering data. 

Calling arguments: 

■ func points to the symbolic H_WAIT 

■ data, length, and position are not applicable to hjvait 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

NOTES 

hjvait uses the WAIT parameters in the h_setparms function call (TWAIT, 
LWAIT and NWAIT). 

RETURN VALUES 

hjvait returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the hjvait call. 

The return code for hjvait will have one of these values: 

HEJSUCCESS: the keyboard is unlocked and ready for input 

HE_INVAL: your application program is not connected to a valid ses- 
sion 

HE_WSCTRL: your application program is connected to WS Ctrl 
HE_BUSY: timeout while still in XCLOCK or XSYSTEM 
HEJNHBT: the keyboard is locked 

HE SYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 
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NAME 

h_wrchar — copy characters to presentation space 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func, data, length, position) 
int *func; 
char "^data; 
int *length; 
int ^position; 

DESCRIPTION 

hjvrchar copies one or more binary characters directly into the current con- 
nected presentation space, starting at the location specified by the PS position 
calling parameter This function is intended for binary image copying into the 
presentation space The copy continues tmtil the field length count is reached; 
no ASCII to EBCDIC conversion will take place. 

hjvrchar operates in STRLEN mode, even if you did not select STRLEN mode 
with h_setparms. This is because hjvrchar copies binary characters and there- 
fore, no EOT escape character can be specified The input data must contain 
the appropriate extended attribute byte following each regular byte if 
extended attribute bytes were specified using the EAB parameter under 
h_setparms. 

Calling arguments: 

■ func points to the symbolic HJVRCHAR 

■ data points to the binary bytes to be copied into the presentation 
space 

■ length points to the length of the location pointed to by data, and 
must be greater than 0 

■ position points to the position within the presentation space where 
the copy will begin. This value must be between: 

□ 1 and 1920 for Model 2s (3840 if you are copying extended attri- 
bute bytes) 

□ 1 and 3564 for Model 5s (7128 if you are copying extended attri- 
bute bytes) 

SEE ALSO 

h_qsys(3X), h_setparms(3X). 

NOTES 

Use the hjvrchar carefully, since it can copy any bit combinations, and no 
checking is done by the HLLAPI library. You are responsible for making sure 
that the byte(s) are correct for your purposes; use other functions if valida- 
tion is desired 

RETURN VALUES 

hjvrchar returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
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calling argument, and is also returned as the function value for the hjvrchar 
call. 

The return code for hjvrchar will have one of these values: 
HE_SUCCESS: hjvrchar was successful 

HEJLNVAL: the HLLAPI program was not connected to a valid 
presentation space 

HE_INHBT: the target presentation space is protected or inhibited, or 
illegal data was sent 

HE_LENGTH: the copy was completed, but the source data was trun- 
cated 

HE_POS: the specified presentation space position is invalid 

HEJSYSERR: a system error was encountered; call the hjjsys function 
to find out the reason for failure 
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NAME 

h wsctrl — work station control 

SYNOPSIS 

#include <xhllapi.h> 

int hllapi(func/ data, length, position) 
int *func; 

struct h_wsctrl_struct *data; 
int ^length; 
int ^position; 

DESCRIPTION 

hjvsctrl provides the programmed operator with block copy and some win- 
dow management capabilities. HLLAPI treats hjvsctrl as a session type, even 
though it is really a "pseudo-session." As a pseudo-session, hjvsctrl can call 
functions against other sessions (e.g., copy blocks of text from other sessions), 
even though it has no presentation space associated with it. 

A "window" is a view of a host session, which in turn is an external manifes- 
tation of a presentation space; recall that a presentation space is a region in 
storage, and therefore, it is not visible to users. In the AT&T 3270 £mulator+ 
HLLAPI implementation, a window occupies the entire screen display, and 
you can view only one window at any given time. You must select fore- 
ground and background colors outside HLLAPI, according to your terminal; 
you cannot alter these features with hjvsctrl. 

A "screen profile" defines the way that presentation spaces will be viewed on 
the screen, and the value of the screen profile will always be "0". 

hjvsctrl does not allow the use of blanks for a presentation space ID, as other 
functions do. Therefore, where a presentation space ID is required, you must 
provide the short name character for that presentation space. 

Calling arguments: 

■ func points to the symbolic HJVSCTRL 

■ data points to a structure of type hjvsctrl_struct that defines the 
desired hjvsctrl request. For all hjvsctrl_struct structures (see the 
"Structures for hjosctrl" sub-section, below), you need to provide the 
"command code" structure member, and some of the other members 
depending on the desired request. The remaining members of the 
structure will be returned by hjvsctrl. 

■ length points to the length of the data string, using the sizeof opera- 
tor on the structure in the data string 

■ position is not applicable to hjvsctrl 

Structures for hjvsctrl 

You control requests to hjvsctrl by specifying a pointer to a structure for each 
desired request; these structures have been declared in the <xhllapi.h> 
header file. You can only send one request to hjvsctrl at a time. 

The AT&T 3270 Emulator+ HLLAPI implementation supports the following 
hjvsctrl requests: 
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Command 


hwsctrl 


Code 


Function Name 


CA 


Change Active Window 


CB 


Copy Block 


RD 


Redraw 


QA 


Query Active Window 


QC 


Query Background Color 


QE 


Query Enlarge State 


QW 


Query Window 


QN 


Query Window Names 



The hjosctrl requests listed below are not supported by the AT&T 3270 Emula- 
tor+ HLLAPI implementation: 



Command 


h_wsctrl 


Code 


Function Name 


AW 


Add Window 


CE 


Change Enlarged State 


CC 


Change Screen Background Color 


cw 


Change Window 


cs 


Clear Screen 


DW 


Delete Window 



If you make any of these requests when you invoke hjvsctrl, the return code 
will be set to "HEJSUCCESS" or "HE_FUNCT/ depending on the option that 
you selected with h_setparms (see the "RETURN VALUES" section, below). 
Thus, if you specified 

UNSUP_OK: the return code will be set to "HE_SUCCESS" 

UNSUP_NG: the return code will be set to "HE_FUNCT" 

UNSUP_VAR: the return code will be set to "HE_SUCCESS" 
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The portion of the <xhllapi.h> file that declares structures for these command 
codes, is: 



#de£ine CMDSIZ 2 
#define NAMES 20 
struct ca data type 
{ 

char ws_cmd[CMDSIZ ] ; 
char ws_equ; 
char ca_scrn; 
char ca_psid; 
} ; /« data from CHANGE ACTIVE «/ 

struct cb data type 
{ 

char ws_cmd[CMDSIZ ] ; 
char ws_equ; 
char cb_psid; 
short cb_srcbeg; 
short cb_srcend; 
char cb_tpsid; 
short cb_tbeg; 
} ; /» data from COPY BLOCK ♦/ 

struct rd data type 
{ 

char ws_cmd [ CMDSIZ ] ; 
char ws_equ; 
char rd_scrn; 
} ; /* data from REDRAW SCREEN */ 

struct qa data type 
{ 

char ws_cmd[CMDSIZ ] ; 
char ws_equ; 
char qa_scrn; 
char qa_psid; 
} ; /« data from QUERY ACTIVE */ 

struct qc data type 
{ 

char ws_cmd[CMDSIZ ] ; 
char ws_equ; 
char qc_scrn; 
char qc.fill; 
char qc_color; 
} ; /♦ data from QUERY COLOR »/ 
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Struct qe data type 
{ 



char ws_cmd[CMDSIZ ] ; 

char ws_equ; 

char qe_f ill [ 2 ] ; 

char qe_enlarge; 

/* data from QUERY ENLARGE ♦/ 



struct qw data type 
{ 



char ws_cmd[CMDSIZ ] ; 

char ws_equ; 

char qw_scrn; 

char qw_psid; 

short qw_rows ; /* number of rows in window ♦/ 

short qw_cols; /* number of cols, in window */ 

short qw_rpos; /♦ row position, upper left corner */ 

short qw_cpos; /* col position, upper left corner */ 

short qw_wcolor;/* window color code »/ 

short qw_bcolor;/« border color code «/ 

short qw_flags;/« control flags */ 

short qw_psrow;/* row on PS of upper left corner */ 

short qw_pscol;/« col on PS of upper left corner «/ 
/* data from QUERY WINDOW »/ 



struct qn data type 
{ 



} 



char ws_cmd[CMDSIZ] ; 

char ws_equ; 

char qn_scrn; 

char qn'uNUSED; 

char qn_names [ NAMES ] ; 

/* data from QUERY NAMES «/ 



/* constants for Query Window function in WSCTRL */ 
#define FOREGROUND WHITE 
#define BACKGROUND BLACK 

#define WCOLOR (FOREGROUND << 3 | BACKGROUND) 



#def ine 
#def ine 
#def ine 
#def ine 
#def ine 



RESERVED 

HIDDEN 

BASECOLOR 

WINDCOLOR 

FLAGS 



00000 
1 
1 
1 

(HIDDEN << 7 I 
RESERVED << 2 
WINDCOLOR) 



BASECOLOR << 1 
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/» Color codes */ 

#defineBLACK 0 

#defineBLUE 1 

#defineRED 2 

#definePINK 3 

#defineGREEN 4 

#def ineTURQUOISE 5 

#de£lneYELLOW 6 

#defineWHITE 7 

/* Row and Column identifiers */ 

#def ineROW_ZERO 0 

#def ineCOLlzERO 0 

/* Screen Profile Identifiers */ 

#define SCREEN_ZERO '0' 

/» Enlarge State Identifiers */ 

#define ENLARGED 1 

#defineNOT ENLARGED 0 



The supported AT&T 3270 Emulator+ HLLAPI hjvsctrl calling and returning 
data strings are explained next. 

Change Active Window, CA 

Changes the active screen profile and presentation space, displays the presen- 
tation space specified in ca_psid (below), and routes keyboard inputs as keys- 
trokes to this presentation space. 

The structure for this request in the <x}tllapi.h> file is ca_data_type; the 
members of this structure describe the following: 

ws_cmd[CMDSIZ]: command code, CA for Change Active Window 

wsjequ: an equal sign, (=) 

ca sern: the screen profile, whose value must be "0" 

ca_psid: the presentation space that HLLAPI is starting 

You must supply all members of the ca_data_type structure, when making this 
request. 

Copy Block, CB 

Copies the contents of a block defined by a set of coordinates in the source 
presentation space, to a block defined by a set of coordinates in a target 
presentation space - the extended attribute bytes are also copied. 

The structure for this request is cbjdata type; the members for this structure 
describe the following: 

ws_cmd[CMDSIZ]: the command code, CB for Copy Block 

wsjequ: an equal sign, (=) 
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cb_psid: short name for the source presentation space 

cb_srcbeg: the starting copy offset in the source presentation 

space; position 1 = row 1, column 1 

cb_srcend: the ending copy offset; position 1 = row 1, column 

1 

cb tpsid: short name for the target presentation space 

cbjtbeg: the starting copy offset in the target presentation 

space; again, position 1 = row 1, column 1 

You must supply all members of the cb_data_type structure, when making 
this request. 

Redraw Screens, RD 

This request redraws the specified screen profile. The AT&T 3270 Emulator+ 
HLLAPI implementation only supports enlarged states, and therefore, the full 
presentation space of the active window will be redrawn. 

The structure for this request is rd_data_type, and its members describe the 
following: 

ws_cmd[CMDSIZ]: command code, RD for Redraw Screens 
wsjequ: an equal sign, (■=) 

rdjscm: active screen profile redrawn; must be "0" 

You must supply all members of the rdjdatajtype structure, when making 
this request. 

Query Active Window, QA 

Returns the short name of the active window in the screen profile. 

The structure for this request is qa_data_type, and its members describe the 
following: 

ws_cmd[CMDSIZ]: command code, QA for Query Active Window 

wsjequ: an equal sign 

qa_scrn: active screen profile; must be "0" 

qa_psid: presentation space short name 

When making this request, you must supply the ws_cmd[CMDSIZ], ws_equ, 
and qa_scm members of the qa_data_type structure, qajpsid will be returned 
by hjosctrl upon execution of the Query Active Window request. 

Query Background Color, QC 

Returns the background color of the screen profile. Use Query Window (QW) 
for the background color of a specific window. 

The structure for this request is qc_data_type; the members of this structure 
describe the following: 

ws_cmd[CMDSIZ]: command code, QC for Query Background Color 
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an equal sign 

the screen profile; must be "0" 
unused filler 

one of the following color codes: 
0: Black 
1: Blue 
2: Red 
3: Pink 
4: Green 
5: Turquoise 
6: Yellow 
7: White 

When making this request, you must supply the ws_cmd[CMDSIZl, ws_equ, 
qc_scrn and qc_fill members of the qcjdatajtype structure, qcjcode will be 
returned by hjvsctrl upon execution of the Query Background Color request. 

Query Enlarge State, QE 

Retuns a flag containing the state of the "enlarge" toggle key. 

The structure for this request is qe_data_type, and its members describe the 
following: 

ws_cmd[CMDSIZ]: command code, QE for Query Enlarge State 

wsjequ: an equal sign 

qejf ill[2]: unused filler 

qejcode: binary enlarge state code, 

0: not enlarged 
1: enlarged 

When making this request, you must supply the ws_cmd[CMDSIZ], wsjequ, 
and qe_fill members of the qe_data_type structure. qe_code will be returned 
by hjvsctrl upon execution of the Query Enlarge State request. 

Query Window, QW 

Returns the following information about a window on the screen profile: 

■ how many rows and columns are in the window 

■ row and column position of the upper left corner of the window 
on the screen 

■ window and border colors 

■ setting of control flags 

■ row and column position of the upper left corner of the window 
on the presentation space 

The structure for this request is qw_data_type; the members of this structure 
describe the following: 



wsjequ: 
qc_scrn: 
qcjill: 
qcjcode: 
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ws_cmd[CMDSIZ]: 

wsjequ: 

qwjscrn: 

qwjpsid: 

qw_rows: 

qwjcols: 

qw_rpos: 

qw_cpos: 

qw_wcolor: 
qwjbcolor: 
qw_flags: 
qw_psrow: 

qw_pscol: 



the command code, QW for Query Window 
an equal sign 

screen profile where the queried window is 
located, and is always "0" 

presentation space short name for the queried win- 
dow 

rows in the queried window 

columns in the queried window 

screen row position of the upper left window 
corner, and is always "0" 

screen column position of the upper left window 
corner, and is always "0" 

window color code 

border color code 

control flags, 

row on the presentation space of the upper left 
corner of the window; the value is always "0" 

column of the presentation space of the upper left 
corner of the window; the value if always "0" 



When making this request, you must supply the ws_cmd[CMDSIZ], ws_equ, 
qw scrn and qw_psid members of the qw_data_type structure. The remain- 
ing members will be returned by hjvsctrl upon execution of the Query Win- 
dow request. 

Query Window Names, QN 

Returns the name of the presentation space displayed in a screen profile. 

The structure for this request is qnjdatajlype, and its members describe the 
following: 

command code, QN for Query Window Names 

an equal sign 



ws_cmd[CMDSIZ]: 

wsequ: 
qn_scrn: 



screen profile of the queried window names, and 
must be "0" 



presentation space short name for the queried win- 
dow names 



qn_psid: 

qn_names[NAMES]: array of window short names 



When making this request, you must supply the ws_cmd[CMDSIZ], ws_equ, 
and qn_scrn members of the qn_data_type structure. The remaining members 
will be returned by hjvsctrl upon execution of the Query Window Names 
request. 
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SEE ALSO 

h_qsys(3X), h_setparins(3X). 

NOTES 

The Query Background Color (QC) request will always return a "0" in the "C 
field for black background color of the base screen; you cannot change the 
color of the screen, and it is not necessarily "black." "Black" is an arbitrary 
choice, and it has no relation to the real color of the screen. This request does 
no useful work in the AT&T 3B environment, and has been included for com- 
patibility with the IBM 3270 Personal Computer HLLAPI specifications. 

The Query Enlarge State (QE) request always returns a "1" in the qe_code 
member field, for "enlarged state"; it can never return a "0" since the "unen- 
larged state" is not supported. 

The Redraw Screens (RD) has no effect in the AT&T 3270 Emulator+ HLLAPI 
environment; it is present for compatibility with the IBM HLLAPI 
specifications. 

RETURN VALUES 

hjvsctrl returns one argument: a return code, defined in the <xhllapi.h> 
header file. The return code is placed at the location pointed to by the position 
calling argument, and is also returned as the function value for the hjvsctrl 
call. 

The return code for hjvsctrl will have one of these values: 

the hjvsctrl operation was successful 

an invalid screen ID was specified, i.e., a screen other 
than "0" was specified 

an error was made in specifying the string length or 
parameters 

hjvsctrl is owned by another session 

the target area for a copy block operation is inhibited or 
protected 

hjvsctrl is an invalid specification 

a system error was encountered; call h_ qsess to find out 
the reason for failure 

this function is not available for the AT&T 3270 Emula- 
tor+ HLLAPI Release 3.0 



HE. 


JSUCCESS: 


HE. 


JNVAL: 


HE. 


PARM: 


HE. 


_WSCTRL: 


HE. 


_INHBT: 


HE 


LENGTH: 


HE. 


_SYSERR: 


HE. 


JFUNCT: 
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NAME 

xlu2clos — power off the logical unit 

SYNOPSIS 

#include <xlu2io.h> 



int xlu2clos(lu_chan) 
unsigned char *lujchan; 

DESCRIPTION 

xluZclos performs a power-off sequence of the logical unit designated by 
*lu_chan, the value rettxrned by an xlu2open{3X) call. Unread data are dis- 
carded. 

xlulclos will fail if any of the following are true, with errapi set as shown: 



[E_ARG1] 


Invalid *lu_chan parameter. 


[E_CNTX] 


*lu_chan does not exist. 


[EJNIT] 


API initialization not performed [xlu2init{3X) not called]. 


[E_BUSY] 


Busy logical unit. 


[E_CTRLIO] 


Communication with controller is terminated abnormally; ses- 




sion powered off (see below). 


[E_TTY] 


Error in controlling terminal device (see below). 


[400+] 


Program check (see Appendix B). 


[500+] 


Communication check (see Appendix C). 



If the call fails with an EjCTRLIO or EJTTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. This does not 
indicate that the call has failed for the input session. The results of this call 
can be determined by use of an xlu2info{2) call for the input *lu_chan. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 
is returned and errapi is set to indicate the error. 
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NAME 

xlu2ctl — logical unit control functions 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2ctl(lu_chan, request, arg, retcod/ sees) 
unsigned char *'lu_chan; 
long request, arg, *retcod; 

long sees; 

DESCRIPTION 

xlulctl performs a specified control function on a logical unit. On input, 
*lu_chan designates an active session-logical unit (LU), returned by an 
xlu2open{,3X) call. The returned value of *lu_chan may be different than the 
input value (see LUEVENT, below), request and arg define the control func- 
tion to be performed on the LU. 

*retcod is a returned value. For an LUEVENT KYjCTRL control function (see 
LUEVENT, below), *retcod is set to the application request key entered by the 
user. For all other values of request on LUD_3270 sessions (see LUDMOD, 
below), *retcod is set to the session status. Bitwise ANDing *retcod with the 
following macros, defined in xapi.h, returns true if the corresponding activity 
has been detected on the lu_chan LUD_3270 session: 

LUR_NOTH ( lu_chan) no activity on session 

LUR_PRES (lu_chan) presentation space update 

LUR_STAT (lu_chan) status update 

LUR_PRNT (lu_chan) host print request 

LUR_BELL (lu_chan) host ring bell request 

sees is the maximum number of seconds xlulctl will wait for the requested 
function to complete. If the call does not complete before sees number of 
seconds have elapsed, the call will fail with errapi set to EJLNTR, and with 
*retcod and *lu_chan updated. If the call completes before sees seconds have 
elapsed, xlulctl will return normally with the appropriate return code. A sees 
value of 0 indicates no timing should be performed. 

The control functions for the values of request are as follows: 

LUAMOD 

For an LU in LUD_3270 mode (see LUDMOD, below) and for a for- 
matted display, sets the screen buffer in the access mode, specified by 
arg: 

0 access all fields (default) 

1 access protected fields only 

2 access unprotected fields only 

For LUDJRAW or LUDJTRAW mode (see LUDMOD, below) or an 
unformatted screen (an unformatted LU-LU session screen or an 
SSCP-LU session), this request is ignored. 
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LUDTIM 

Sets the number of seconds, specified by arg, that each API call 
display is maintained on the screen during LUVJTRC mode (see 
LUVMOD, below). The default value is zero. If arg specifies a nega- 
tive value, it is treated as zero. 

LUDMOD 

Changes the data transfer mode for the LU, as set by xlu2open{3X), to 
the mode specified by arg: 

LUD_RAW Data is transferred between the host and the user 
application in raw form, unaltered and unprocessed, 
using any (or no specific) type of data stream. 

LUDJTRAW Data is transferred between the host and the user 
application in transparent raw form, unaltered and 
unprocessed, using any (or no specific) type of data 
stream. 

LUD_3270 Data is transferred between the host and the user 
application through the 3278/9 screen buffer with 
data stream processing including validation and 
translation. 

If the LU is busy [Intervention Required (IVR) mode; see, e.g., 
KY_BUSY under LUEVENT], the data transfer mode is not altered and 
an E BUSY error is returned. If the LU is in the process of sending 
data to or receiving data from the controller (i.e., the LU's keyboard 
is locked), the data transfer mode is not altered and an OPIJFUNCT 
error is returned. 

If a session's data transfer mode is changed so that a different type of 
data stream will be used between the emulator and host, the user 
application program should send notification of the change to the 
host. In this case, the host application should be in receive state. 

LUVMOD 

Sets the screen buffer visibility mode for the LU, as specified by arg: 
LUV_NON Screen update is disabled. 
LUV DSP Screen update is enabled. 

LUVJTRC Screen update is enabled and a visual trace of API 
calls is provided in the Operator Information Area, to 
aid in debugging (see Appendix D). 

See LUDTIM, above. 

LUV_NTD Screen update goes to stdout, but stdin does not have 
to be a terminal device. 

LUEVENT 

Causes the event specified in arg to be reported to the physical unit. 
For this value of request, xlulctl will block until the controller ack- 
nowledges and completes the processing of the event. The LU's 
screen buffer may also be transmitted. Control is returned to the 
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application program as described below. 

For an LU in LUD_3270 mode (see LUDMOD, above), the valid values 
for arg are: 

KY_ATTN 3278/9 ATTN Key (SNA only) 

KYJBAKTAB move cursor left to the beginning of the previous 
field 

KYJBUSY enter IVR mode 
KY_CLEAR CLEAR key 

KYjCTRL passes control of the terminal emulation process 
interface from application program to interactive 
user, until the user ends control with an [ESC] 
FD. 

KY_DOWN_A move cursor down one line 

KY_E_EOF 3278/9 Erase to End of Field key 

KY_E_INPUT 3278/9 Erase Input key 

KY_ENTER ENTER key 

KY_HOME move cursor to home position 

KY_LEFT_A move cursor left one position 

KY_NMSG await next message from the controller /host (no 
need for keyboard to unlock) 

KY_PAn 3278/9 PROGRAM ACCESS keys 1, 2, 3 

KY_PEND awaits the next host event. This request is par- 
ticularly useful when the session resulting from 
an xluZopen call is INACTIVE and screen update 
is not forthcoming. 

KY_PFn 3278/9 PROGRAM FUNCTION keys 1, 2, 3, ...24 

KYJRESET 3278/9 RESET key 

KY_RIGHT_A move cursor right one position 

KY_SYS_REQ 3278/9 SYS_REQ key (SNA only) 

KY TAB move cursor right to the beginning of the next 

field 

KY_TST_REQ 3278/9 TEST_REQ key (BSC only) 

KYJJNBUSY resume communication with host after KY_BUSY 
request 

KY_UP_A move cursor up one line 

KY_WAIT awaits the next host screen update 

For an LU in LUD_RAW or LUDJTRAW mode (see LUDMOD, above), 
only the following values of arg are valid: 
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KY_ATTN 3278/9 ATTN key (SNA only) 
KY_BUSY entering IVR mode 

KY_NMSG await next message from the controller/host (no 
need for keyboard to unlock) 

KYJPEND awaits the next host event. This request is par- 
ticularly useful when the session resulting from 
an xlulopen call is INACTIVE and screen update 
is not forthcoming. 

KY_SYS_REQ 3278/9 SYS_REQ key (SNA only) 

KY_TST_REQ 3278/9 TEST_REQ key (BSC only) 

KY_UNBUSY resume communication with host after KY_BUSY 
request 

For all modes, if the LU is in the process of sending data to or receiv- 
ing data from the controller (i.e., the LU's keyboard is locked), the 
event (excluding KY_WAIT, KY_PEND and KY_CTRL) is rejected with 
an OPI_FUNCT error. 

The calling program is blocked until one of the following conditions 
occurs: 

• For a cursor movement request, following cursor movement. 

• For a request on any LU that results in communication with the 
host or the controller, until keyboard unlock. 

• For KY WAIT on any LU, until the host responds with a screen 
update and keyboard unlock. KY WAIT blocks until the host 
updates any LU's screen buffer and the keyboard is unlocked. • 

• For KY_PEND on any SNA LU, when a host or controller event 
is received, resulting in valid session ownership, with keyboard 
unlock. 

On an LU which is connected to an SNA controller, KY_PEND 
blocks until the host or the controller places an LU in a valid ses- 
sion with the keyboard unlocked. On a LU which is connected 
to a BSC controller, KY PEND blocks the application program 
until the keyboard is unlocked. 

• For KY PEND and KY_NMSG, when a segment arrives on a 
LUD_RAW or LUD_TRAW channel 

For KY_CTRL, when the interactive user strikes KY_CTRL, 
KYJPREVS, KY_NEXTS, KYJDENT, KY_SHELL, or KY_U1 
through KYJJIO. 

In this case, the application request key entered by the user is 
returned in *retcod. 

For LUEVENT, the returned value of *lu_chan may be different then 
the input value, corresponding to another session on which a previ- 
ously initiated event has completed. 
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LUEVIMED 

Causes the event specified in arg to be reported to the physical unit. 
For this value of request, xlulctl will block until the controller ack- 
nowledges the event, but does not wait for the completion of the 
event. The LU's screen buffer may also be transmitted. Control is 
returned to the application program as described below. 

For an LU in LUD_3270 mode (see LUDMOD, above), the valid values 
for arg are: 

KY_ATTN 3278/9 ATTN key (SNA only) 

KY_BAKTAB move cursor left to previous field 

KY_BUSY entering IVR mode 

KY_CLEAR CLEAR key 

KY_DOWN_A move cursor down one line 

KY_ENTER ENTER key 

KY_E_EOF 3278/9 Erase to End of Field key 

KY_EJNPUT 3278/9 Erase Input Key 

KY_HOME move cursor to home position 

KY_LEFT_A move cursor left one position 

KY_NMSG await next message from the controller/ host (no 
need for keyboard to unlock) 

KY_PAn 3278/9 PROGRAM ACCESS keys 1, 2, 3 

KY_PFn 3278/9 PROGRAM FUNCTION keys 1, 2 ,...24 

KY_RESET 3278/9 RESET key 

KY_RIGHT_A move cursor right one position 

KYJ5YS_REQ 3278/9 SYS_REQ key (SNA only) 

KYJTAB move cursor right to next field 

KY_TST_REQ 3278/9 TEST_REQ key (BSC only) 

KY_UNBUSY resume communication with host after KY_BUSY 

KY_UP_A move cursor up one line 

If the LU is in the process of sending data to or receiving data from 
the controller (i.e., the LU's keyboard is locked), the event is rejected 
with an OPIJFUNCT error. 

For KY_NMSG, the returned value of *lu_chan may be different than 
the input value, corresponding to another session on which a mes- 
sage has been received from the controller /host. If there is no mes- 
sage for any session, the call will return with *lu_chan set to sessjnax 
[see xlu2info{3X)l 

For an LU in LUD_RAW or LUDJTRAW mode (see LUDMOD, above), 
only the following values of arg are valid: 
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KY_ATTN 3278/9 ATTN key (SNA only) 
KY_BUSY entering IVR mode 

KY_NMSG await next message from the controller/host (no 
need for keyboard to unlock) 

KY_SYS_REQ 3278/9 SYS_REQ key (SNA only) 

KY_TST_REQ 3278/9 TEST_REQ (BSC only) 

KY_UNBUSY resume communication with host after KY_BUSY 

For LUEVIMED, the calling program is blocked until one of the fol- 
lowing occurs: 

• The cursor is repositioned on the LUD_3270 LU. 

• All relevant data for the LU are transferred to the controller. 

Note: Although LUEVENT and LUEVIMED appear to operate in a simi- 
lar manner, they return to the caller under different conditions. 
LUEVIMED merely waits for the controller to acknowledge the event, 
without waiting for completion of processing. LUEVENT waits for the 
controller to acknowledge and also complete processing of an event. 

xlulctl will fail if any of the following are true, with errapi set as shown: 

[E ARGl] Invalid *lu_chan parameter. 

[E_ARG2] Invalid value of request. 

[E_ARG3] Invalid arg. 

[E_ARG4] retcod is the null pointer. 

[EJNIT] API initialization not performed [xluliniti'iX) not called]. 

[E_CNTX] *lu_chan does not exist. 

[E_BUSY] Busy logical unit. 

[E_XLIB] Necessary library function(s) excluded at link time. 

[OPI_WHAT] Invalid operation. 

[OPI_FUNCT] Invalid operation. 

[E_DMODE] LU is in LUDJRAW or LUDJTRAW mode, or could not enter 
requested data transfer mode. 

[E BNDREJ] Host mismatch on buffer size; bind rejected. 

[E DOVFLO] Raw outbound data has overflowed internal queue. 

[E_DCOD] LUDJTRAW is unavailable on ASCII line. 

[EJENTR] sees is non-zero and the function did not complete in sees 

seconds or this call was blocking and an xlu2intr(3X) was 
issued (see below). 

[EjCTRLIO] Communication with controller is terminated abnormally; ses- 
sion powered off (see below). 
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[EJTTY] 



Error in controlling terminal device (in LUVJDSP mode; in 
LUVJTRC mode; in LUV_NON/LUV NTD mode on 
LUEVENT with KY_CTRL or on LUDTIM). See below. 



[400+] 
[500+] 



Program check (see Appendix B). 



Communication check (see Appendix C). 



If the call fails with an E_CTRLIO or E_TTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. Also, if the 
call fails with E_INTR, this does not indicate that the call has failed. The con- 
trol function may succeed at a later time. The results of the call can be deter- 
mined by use of an xlu2info{2) call for the input *lu_chan. 



Before selecting LUD_RAW and LUDJTRAW (under LUDMOD), you must 
turn the display off with LUV_NON (under J-,UVMOD). Otherwise, you will 
obtain an ERRAPI return value of E_DMODE. 



Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 
is returned and errapi is set to indicate the error. 



NOTES 



DIAGNOSTICS 
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NAME 

xluZfunc — perform special functions on the logical unit 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2func(lu_chan, func, name, sees) 
unsigned char *lu_chan; 
long func; 

unsigned char *name; 
long sees; 

DESCRIPTION 

xlulfunc performs various special functions on the logical unit specified by 
*lu_chan, the value returned by an xlu2open{3X) call. The functions are 
specified by the value of func: 

LUPRND print capability disabled 

LUPRNF print to a file 

LUPRNC print request command 

LURSET clear inhibit condition 

name is the function object, according to func: 

LUPRND name may be NULL 

LUPRNF file path name 

LUPRNC command string 

LURSET RESET-INHIBIT-condition mode 

For print functions (LUPRND, LUPRNF and LUPRNC), xlulfunc fails with 
errapi set to EJDMODE if the *lu_chan session is not in LUD_3270 mode. 

LURSET controls the resetting or clearing of inhibit conditions before return- 
ing from subsequent API system calls. For LURSET, name may be: 

LUI_RSYS Reset SYSTEM inhibit conditions (default) 

LUI_SYS SYSTEM inhibit conditions not automatically reset 

sees is the maximum number of seconds xlulfunc will wait for the requested 
function to complete. If the call does not complete before sees number of 
seconds have elapsed, the call will fail with errapi set to E_INTR. If the call 
completes before sees seconds have elapsed, xlulfunc will return successfully. 
A sees value of 0 indicates no timing should be performed. 

xlulfunc will fail if any of the following are true, with errapi set as shown: 

[E_ARG1] Invalid lu_chan parameter. 

[E_ARG2] Invalid func parameter. 

[E PATH] Invalid name parameter for func LUPRNC or LUPRNF. 
[EJCOND] Invalid name parameter for func LURSET. 
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[EJNIT] API initialization not performed [xlu2mit{3X) not called]. 

[E_CNTX] *lu_chan does not exist. 

[E_DMODE] func is LUPRND, LUPRNF or LUPRNC and lu_chan is in 
LUD_RAW or LUD_TRAW mode. 

[E_DOVFLO] Raw outbound data has overflowed internal queue. 

[E_INTR] sees is non-zero and the function did not complete in sees 

seconds or this call was blocking and an xlu2intr(3X) was 
issued (see below). 

[EjCTRLIO] Communication with controller terminated abnormally; ses- 
sion powered off (see below). 

[E_TTY] Error in controlling terminal device (LUV_DSP and LUV_TRC 

modes only, see xlulopen). Also see below. 

If the call fails with an E_CTRLIO or E_TTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. Also, if the 
call fails with EJLNTR, this does not indicate that the call has failed. The 
function may succeed at a later time. The results of the call can be deter- 
mined by use of an xlu2info{l) call for the input *lu_chan. 



DIAGNOSTICS 

Upon successful completion, a value of 0 is returned, 
is returned and errapi is set to indicate the error. 



Otherwise, a value of -1 
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NAME 

xlu2gets — get a string from the LUD_3270 logical unit's screen buffer 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2gets(lu_chan, s, n) 
unsigned char '^lu_chan, 
unsigned char *s; 
long •n; 

DESCRIPTION 

xlulgets retrieves the data from the screen buffer field of the LUD_3270 mode 
logical unit specified by *lu_chan, the value returned by an xlu2openi3X) call. 
The field is determined by the buffer location to which the cursor is currently 
pointing. The contents of the field are converted to a null terminated ASCII 
string and placed into the user buffer pointed to by s. 

On call, *n specifies the maximum number of characters the user buffer can 
hold excluding the terminating null. On return, *n is set to the number of 
characters actually placed into the user buffer. For a formatted display, a pro- 
tected or unprotected field can be retrieved and the maximum returned value 
of *n is the number of characters permitted in the field. For an unformatted 
display, this is the requested length. If the cursor is positioned to an attribute 
byte in a formatted display, the call will fail with errapi set to E_ACCS. 

For a formatted screen buffer, the cursor is repositioned to the beginning of 
the next protected or unprotected field, depending on the value of the access 
mode [LUAMOD, see x/«2cf/(3X)] for this LU (consecutive attributes are 
skipped). For an unformatted screen buffer, the cursor is repositioned to the 
first location following the end of the transferred string. 

If a screen wrap occurs during string transfer, the field transfer is continued 
until the field or the requested number of characters is exhausted. The cursor 
is not positioned to the next field and an EjOFFB warning code is returned in 
errapi. 

Data character translation of the data stream is performed according to the 
character echo string definitions specified in the customization file, scjfil, in 
the xlu2init{3X) call. Null characters in the screen buffer field are not 
translated. They are transferred as nulls to the user buffer, so that the return 
string may contain embedded nulls. 

xluZgets will fail if any of the following are true, with errapi set as shown: 
[E ARGl] Invalid lu_chan parameter. 

[E_ARG2] s is the null pointer. 

[E_ARG3] n is the null pointer or the value of *n is less than 1. 
[EJNIT] API initialization not performed [xlu2init(3X) not called]. 

[E_CNTX] *lu_chan does not exist. 

[E_DMODE] *lu_chan is in LUD_RAW or LUDJTRAW mode. 
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[E_BUSY] 


Busy logical unit. 


[OPIJVHAT] 


Invalid operation. 


[OPI_FUNCT] 


Invalid operation. 


[E_ACCS] 


Cursor positioned to an attribute byte 


[E_CTRLIO] 


Communication with controller is terminated abnormally; ses- 




sion powered off. See below. 


[E_TTY] 


Error in controlling terminal device (LUV_DSP and LUVJTRC 




modes only, see xlulopen). See below. 


[400+] 


Program check (see Appendix B). 


[500+] 


Communication check (see Appendix C). 



If the call fails with an E CTRLIO or E TTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. This does not 
indicate that the call has failed for the input session. The results of this call 
can be determined by use of an xlu2mfo{2) call for the input *lu_chan. 



DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a negative 
value is returned. A return value of -1 indicates a failure and errapi is set to 
indicate the error. A return value of -2 indicates a warning condition and 

errapi is set as follows: 

EjOFFB Cursor is off the screen buffer boundary. 
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NAME 



xlu2info — obtain 3278/9 status line and cursor position information 



SYNOPSIS 

include <xlu2io.h> 

int xlu2info(ibuf) 
XLU2IBUF »ibu£; 

DESCRIPTION 

xlulinfo returns information regarding the session-logical units that have been 
established by this process, including the contents of the 3278/9 status line 
and cursor position. 



The information is returned in an XLU2IBUF structure pointed to by &uf, 
defined in xapi.h, which contains the following elements: 



unsigned char act_dt; 



unsigned char lu_chan 
unsigned char model; 

struct 
{ 

unsigned cihar lu_cpn; 
unsigned char lu'act; 



long luamod; 
Icoig luvncd; 

IcKig ludtim; 
long lixdmod; 

long lusnod; 
long luisdfl; 
imsigned ohar luirst; 

unsigned char lubusy; 
unsigned char «pres_spc; 
vmsigned char «extn~bu£; 
short »attr_tita; 
int attr_lini; 
short c_iiiie; 
short c~col; 
short cjpos; 
short c_beg; 
short c~end; 
unsigned char c_att; 
unsigned char c'fxm; 

long err_cand; 
unsigned~char ke;^_lck; 
unsigned char wait~lck; 
vmsigned char inhb'lcdc; 
short err_400; 



A the bit in positions "3210" indicates 

activity on the oarresponding lu_cihan 

session-logical unit »/ 

/* index to oh dat structure */ 

A 3278/9 node! nuniaer: 2,5 »/ 

A ch_dat structure */ 

A lu oonnectian is open indicator */ 
A session activity; this can be examined 
in the same manner as_the retcod argument of the 
xlu2ctl function. NOTE: Only LUD_3270 session 
(see luditod) activity is updated */ 
A access all/only prot:ected/only unprot fids */ 
A screen visibility mode on/off with qpia in 
TE/API mode «/ 

A MPL function display time on opia in sec */ 
A data transfer mode: 

LaD_PAW, USDJSm or LUD_3270 */ 
A requestied security mode: DF7HI_SBC0R */ 
A default security mode: HI/llM_SEC[]R «/ 
A Inhibit condition reset 

(for values, see xapi.h) */ 
A =1, if lu is in IVR mode; otherwise, =0 */ 
A presentation sfpace address */ 
A extended attribute buffer address */ 
A attribute bit map address */ 
A attribute bit map size (short units) «/ 
A current line Tsaasbsr */ 
A current colvnnn number »/ 
A current cursor position */ 
A beginning of current field «/ 
A end of current field */ 
A current field attribute */ 
A current screen buffer: 

unfarnat±ed (0)/formatted (1) */ 
A API-detected error */ 
A keyboard state: WAIT or INHIBIT */ 
A keu^xard state: WAIT (1)/clear (0) */ 
A ke5*oard state: INHIBIT (2)/clear (0) */ 
A 400 series error messages */ 
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short err_500; /♦ 500 series error message */ 

short opia; /* terminal status (for valiies, 

see iiihibit cxsndition section in scapi.h) */ 
unsigned char bscanod; /« 1=bsc, 0=sna «/ 
unsigned char line.cihr; /* data code: ASCII or EBCDIC */ 
short nBx_siz; " /* naxinum xlu2writ segment size */ 
\msigned dhar sna_own; /* if sna, owner (for values, 

see session ownership section in xapi.h ) */ 
unsigned char lu_prt; /* lu port number */ 
\msigned char pu_nam[PA3HSIZ] ; A controller path name */ 
unsigned char prn_f1[PAlHSlz]; /* printer path name */ 
long pmjnd; ~ /* -pcxciasx: assignment mode. O^none, 1=£ile, 

2=ocnnend »/ 

} ch_dat[sess_nBx] ; 

lu_chan, the index to ch_dat, is the value returned by xluZopen. sessjnax is the 
maximum number of logical units (currently 4) that can be open at one time 
by one process, defined in xapi.h. 

The cause of an error return from an API system call is indicated in errapi. If 
the error is detected during function call parameter validation, only errapi is 
set. If the returned error is due to a logical unit INHIBIT condition, errapi and 
the opia field are set. If the error is due to a 400 or 500 series error, errapi and 
the err_400 or the err_500 field are set. Finally, if the error is due to any of the 
other error conditions listed for the call, errapi and the err_cond field are set. 

DIAGNOSTICS 

Upon completion, a value of 0 is returned. There are no defined error returns. 
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NAME 

xluZinit — initialize terminal function library 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2init (sc_ifil, ky_i£il, rt_m£il, t_inodl^ ds_vers) 
unsigned char *sc_i£il/ *ky_ifil, *rt_m£il, t_modl, dsjveis; 

DESCRIPTION 

xlulinit performs local API initialization functions for the calling process 
including reading the runtime files and assigning the terminal model number. 
scjfil is the pathname of the screen control customization object file, output of 
the scinit utility, described in the AT&T 3270 Emulator+ System Administrator's 
Guide, kyjfil is the pathname of the keyboard mapping customization object 
file, output of the kyinit utility, described in the Administrator's Guide, rtjnfil is 
the pathname of the runtime message object file, described in the 
Administrator's Guide, tjnodl is the 3278/9 terminal model number (2 or 5). 

dsjaers determines whether extended field attributes will be processed. If 
ds_vers is set to LUD_EXT, extended field attributes will be displayed if screen 
visibility is enabled [see LUVMOD in xlu2ctl{3X)]. If dsjvers is not set to 
LUD_EXT (i.e., set to LUD_RAW, LUDJTRAW or LUD_3270), extended field 
attributes orders and commands will be ignored. 

xlulinit is performed only once in an API program, and must precede any 
other API call. 

xlulinit will fail if any of the following are true, with errapi set as shown: 

[E_ARG1] scjfil is the null pointer. 

[E_ARG2] kyjfil is the null pointer. 

[E_ARG4] Invalid parameter. 

[E_SCTL] Error in opening /reading scjfil 

[EJKCTL] Error in opening /reading kyjfil 

[E_RTMG] rtjnfil is invalid. 

[E_MODL] Physical terminal (as described by scjfil) can not support 
model number. 

[E_INIT] xlulinit previously called for this API process. 

[E XLIB] Necessary library function(s) excluded at link time. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 
is returned and errapi is set to indicate the error. 
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NAME 

xluZintr — interrupt API call 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2intr() ; 
DESCRIPTION 

This call is intended to be used from an API application signal catching rou- 
tine. xluZintr will cause to abort certain API function calls previously issued 
by this process which are currently in progress and are also currently blocked 
from completing. The calls capable of blocking are xlu2ctl{3X), xlu2func{3X), 
xlu2open{3X) and xlu2writ(3X). When the signal catcher completes and the 
interrupted process resumes, any of these calls in the described state will 
immediately terminate processing and return a failure with errapi set to 
EJNTR. 

When a signal is caught during execution of an API application, the signal 
catching routine can not call any other API functions since the signal may 
have occurred during execution of an API function and API does not allow 
concurrent calls from the same process. 

Signals do not automatically cause API function calls to be interrupted. 
xlu2intr allows the catching routine to notify the mainline process of the 
occurrence of the signal, such as a timer, by a procedure such as setting a flag. 
When the mainline application recognizes the flag, it can handle the event 
which has been signaled and make other API calls as required. 

xlu2intr will fail if the following is true with errapi set as shown: 

[EJ[NIT] API initialization not performed 

DIAGNOSTICS 

Upon successful completion, one of the following values is returned: 

0 No API call in progress 

1 API function in progress 

2 Terminal Emulation in progress 

Otherwise, a value of -1 is returned and errapi is set to indicate the error. 
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NAME 

xlu2open — power on the logical unit 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2open (lujchan, pu_name, lu_port, ludmod/ luvmod, lusmod, sees) 
unsigned char "^lujchan, *pu_name/ *'lu_port; 
long ludmod, luvmod, "^lusmod, sees; 

DESCRIPTION 

xlulopen requests the services of a port within the specified BSC or SNA 3274 
controller and performs a power-on sequence of a logical unit with respect to 
the host, pujiame points to a character string containing the name of the 3274 
controller process communication path. 

On call, lujjort points to a character string containing the 3274 controller port 
number. lu_port may also point to a string containing multiple port numbers 
separated by a comma or hyphen, representing several (comma) or a range of 
acceptable ports. A null lujJort pointer indicates that the user will accept any 
available 3270 controller port. The controller port number will be returned in 
the lu_prt field of the XLU2IBUF structure for this session [see 
xlu2mfo{3X)]. Values contained in *lujfort can be the following, according to 
the type of controller specified in *pu_name. 

Standard 3270 SNA 0- 31 
3270 BSC 0- 31 
Enhanced 3270 SNA 1 - 254 

These values also depend on the total number of logical units for which the 
controller is configured, as described in the AT&T 3270 Etnulator+ System 
Administrator's Guide. 

ludmod indicates the mode of data transfer between the host and the API user 
application program: 

LUDJRAW Data is transferred between the host and the user applica- 
tion in raw form, unaltered cmd unprocessed, using any 
(or no specific) type of data stream. 

LUDJTRAW Data is transferred between the host and the user applica- 
tion in transparent raw form, unaltered and unprocessed, 
using any (or no specific) type of data stream. 

LUD_3270 Data is transferred between the host and the user applica- 
tion through the 3278/9 screen buffer with data stream 
processing including validation and translation. 

LUDJTRAW is ignored if *pu_name is not a BSC controller. If the controller is 
BSC and LUDJIRAW is selecteds, but the character set has been configured as 
ASCII (see "BSC Configuration" in the Administrator's Guide), xlulopen will fail 
with errapi set to E_XPRNT. 

luvmod indicates the screen visibility mode for the logical unit: 
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LUV_NON Screen update is disabled. 
LUV DSP Screen update is enabled. 

LUVJTRC Screen update is enabled and a visual trace of API calls is 
provided in the Operator Information Area, to aid in 
debugging (see Appendix D). Also see LUDTIM in 
xlu2ctl{3X). 

LUV_NTD Screen update goes to stdout, but stdin does not have to 
be a terminal device. 

lusntod is valid only if *pujtame is a SNA controller and will be ignored for 
BSC. On call, *lusmod indicates how the security mode for the logical unit 
should be set: 

DF_SECUR Default to what is specified in the cluster controller cus- 
tomization file (see below and "SNA Configuration" in the 
Administrator's Guide). 

HIJSECUR The security mode of the logical unit is set to high secu- 
rity. 

On successful return, *lusmod specifies the default controller configuration set- 
ting (see the Administrator's Guide): 

NMJSECUR An xlu2closi3X) call may not deactivate the session owner- 
ship established by the host. 

HI_SECUR An xlulclos call is ensured to deactivate the session own- 
ership established by the host. 

The calling program is blocked until power-on is completed or sees seconds 
have elapsed. Power-on completion occurs when the logical unit has valid 
session ownership (SNA only), with keyboard unlock, the power-on is 
rejected, or EjCTRLIO error is detected on this or any other session. 

sees is the maximum number of seconds xlulopen will wait for this function to 
complete. If the call does not complete before sees number of seconds have 
elapsed, the call will fail with errapi set to E_INTR. If the call completes 
before sees seconds have elapsed, xlulopen will return successfully. A sees 
value of 0 indicates no timing should be performed. 

xlulopen will fail if any of the following are true, with errapi set as shown: 

[E PATH] pujiame is the null pointer. 

[E_ARG3] Invalid lu_port parameter. 

[E_ARG4] Invalid ludmod parameter. 

[E_ARG5] Invalid luvmod parameter. 

[E_SECUR] Invalid lusmod parameter. 

[E INIT] API initialization not performed [xlulinit{3X) not called]. 

[E_SESLIM] Number of sessions exceeds limit. 

[E_XLIB] Necessary library function(s) excluded at link time. 
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[E_RSRC] Controller has insufficient resources, i.e., there are no ports 
left. 

[E_BNDREJ] Host mismatch, bind rejected. 

[EJTRMBSY] SNA/BSC terminal is busy. 

[E_HOSTID] Illegal SNA/BSC host identification. 

[E CNTID] Illegal controller identification. 

[E_LINID] Illegal line identification. 

[EJELSIZE] Bind and device size mismatch; bind rejected. 

[E_XPRNT] Request for transparent line characteristic (LUDJTRAW) 
rejected. 

[E_INTR] sees is non-zero and the function did not complete in sees 

seconds or this call was blocking and an xlu2intr{3X) was 
issued. 

[EjCTRLIO] Error in opening /reading /writing on commimication path to 
controller. 

[E_TTY] Error in controlling terminal device (LUV_DSP and LUVJTRC 

modes only). 

[400+] Program check (see Appendix B). 

[500+] Communication Check (see Appendix C). 

If the call fails with an EjCTRLIO or EJTTY error, the error may have 
occurred on another session and does not indicate that the call has failed. 
Also, if the call fails with E INTR, this does not indicate that the call has 
failed. The open may succeed at a later time. The results of the call can be 
determined by use of an xlu2info{2) call for the input *lu_ehan. 

DIAGNOSTICS 

Upon successful completion, xlulopen returns 0 with *lu_chan set to an integer 
in the range 0 to 3 [see sessjnax in xlu2info{3X)\. This value represents a logi- 
cal unit channel for this process which will be referenced in all subsequent 
API calls for this logical unit. 

Otherwise, a value of -1 is returned and errapi is set to indicate the error. For 
all errors other than E_INTR, 400+ and 500+, the logical unit is considered 
closed. In order to power on the logical unit, the xlu2open call must be 
repeated. 
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NAME 

xlu2puts — put a string to the LUD_3270 logical unit's screen buffer 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2puts(lu_chan, s, n) 
unsigned char *lu_chan, *s; 
long *n; 

DESCRIPTION 

xlulputs writes a string to the screen buffer at the current cursor position of 
the LUD_3270 mode logical imit specified by *lu_chan, the value returned by 
an xlu2open(3X) call. 

The null terminated string is retrieved from the user buffer pointed to by s. If 
the screen field is smaller than the length of the string (excluding the ter- 
minating null), the string is truncated when placed into the screen buffer. In 
this case, errapi is set to OPIJTOOM, but xlulputs does not fail. In all cases, 
xlulputs retwns in *«, the number of characters actually written to the screen 
buffer. 

For a formatted screen buffer, the cursor is repositioned to the beginning of 
the next protected or unprotected field, depending on the value of the access 
mode [LUAMOD, see xlu2ctH3X)] for this LU (consecutive attributes are 
skipped). For an unformatted screen buffer, the cursor is repositioned to the 
first location following the end of the transferred string. 

If a screen wrap occurs during string transfer, the string transfer is continued 
until the field or the string is exhausted. The cursor is not positioned to the 
next field and an EjOFFB warning code is retiuned in errapi. 

If an error (e.g. OPI_NUM) occurs during string transfer, the transfer is 
aborted (part of the string is transferred until the error is encountered) and 
the cursor is not positioned to the next field. 

Character translation on the input string is performed according to the key- 
board mapping specified by the customization file, kyjfil, in the xlu2init(3X) 
call. Only data or numeric characters are allowed in the string. 

xlulputs will fail if any of the following are true, with errapi set as shown: 



[E_ARG1] 


Invalid *lu_chan parameter. 


[E_ARG2] 


s is the null pointer. 


[E_ARG3] 


n is the null pointer. 


[EJNIT] 


API initialization not performed [xlu2init{3X) not called]. 


[EjCNTX] 


*lu_chan does not exist. 


[E_DMODE] 


*lu_chan is in LUD_RAW or LUDJTRAW mode. 


[E_BUSY] 


Busy logical unit. 


[E_ACCS] 


Access mode violation. 
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[OPIJMUM] Non-numeric data entered in numeric field. 
[OPI_ELSE] Improperly positioned cursor. 

[OPIjrOOM] Field overflow (however, xluZputs does not return -1; returns 
the size of the string transferred in n). 

Bad key translation. 

Invalid operation. 

Invalid operation. 

Communication with controller is terminated abnormally; ses- 
sion powered off. See below. 

Error in controlling terminal device (LUV_DSP and LUV_TRC 
modes only, see xlulopen). See below. 

Program check (see Appendix B). 

Communication check (see Appendix C). 

If the call fails with an E_CTRLIO or E_TTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. This does not 
indicate that the call has failed for the input session. The results of this call 
can be determined by use of an xlu2info{2) call for the input *lu_chan. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a negative 
value is returned. A return value of -1 indicates a failure and errapi is set to 
indicate the error. A return value of -2 indicates a warning condition and 
errapi is set as follows: 

EjOFFB Cursor is off the screen buffer boundary. 



[OPI_BAD] 
[OPI_WHAT] 
[OPI_FUNCT] 
[E_CTRLIO] 

[E_TTY] 

[400+] 
[500+] 
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NAME 

xlu2read — read the next raw segment on the LUDJRAW/LUDJTRAW logical 
unit 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2read(lu_chan, segmt) 
unsigned char *Iu_chan; 
RAWSEG *segint; 

DESCRIPTION 

xlulread performs a data block read operation on the LUD_RAW/LUD_TRAW 
logical unit channel which has the oldest queued data. The returned value of 
*lu_chan is set to the logical unit, which will be one of the values returned by 

an xlu2open{3X) call. 

The elements of the RAWSEG structure, defined in xapi.h, are described in 
xlu2writ{3X) . xlulread uses segmt->s and segmt- >n as inputs and uses 
all elements, including s e gmt - > s and s e gm t - > n, as outputs. 

xlulread executes a non-pended read, returning to the caller even if nothing is 
read. Two types of messages are read: data segment and control. A control 
message is notification of status update, a bind or a host transmission comple- 
tion, xlulread tetvans in segmt->typ: 

LUR_NUL if nothing is read 

LUR_END if chain complete /cancel is detected 

LURJBND if a bind is detected (SNA only) 

LURJSTS if status is updated 

LUR_DAT if data is read 

If segint->typ is set to LUR_DAT, a data segment message has been read 
and is contained in the buffer pointed to by segmt->s. The seq, blk and 
cmd fields of RAWSEG are significant only in this case. 

xlulread reads a data block of up to segmt->n bytes into *segmt->s. If 
the input value of segmt->n is less than readjnax (defined in xapi.h), data 
will be silently discarded. If the logical unit channel on which the data is 
read is connected to a BSC controller, the data returned in segmt- >s is the 
data received following STX. On return, segmt- >n is set to the actual 
number of bytes read. 

A data block returned by xlulread can have a maximum length of readjnax 
bytes. If the host application sends data in block sizes greater than readjnax, 
xlulread will set the value of segmt->seq to indicate the segmentation per- 
formed by the communication protocol. segmt->seq indicates the relative 
position of the read data segment in a sequence of received data segments 
forming a data block. The segmentation is performed by the controller on a 
block of data which it receives from the host, xlulread returns in segmt- 
>seq: 
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LUJFIS first in segment 

LU_MIS middle in segment 

LU LIS last in segment 

LU OIS only in segment 

If blocking is performed by the host, xluZread returns in segmt->blk an 
indication of the relative position of the read data block in a sequence of 
received data blocks forming a command. In this case, segmt->blk can 
have the values: 

LU_DSB first data block 

LU_DSC middle data block 

LU_DSE last data block 

LU_DSO only data block 

In the case of a BSC controller where command chaining is performed by the 
host, xluZread returns in segmt->cmd an indication of the relative position 
of the read data block in a sequence of received commands forming a chain. 
In this case, segmt->cmd can have the values: 

LU DSN new chain 

LU_DSS same chain 

xlulread will fail if any of the following are true, v.'ith errapi set as shovvn: 

[E ARGl] Invalid *lu_chan parameter. 

[E_ARG2] segmt is the null pointer. 

[EJNIT] API initialization not performed [xlu2init{3X) not called]. 

[E_CNTX] *lu_chan does not exist. 

[E_DMODE] *lu_chan is in LUD_3270 mode. 

[E_BUSY] Busy logical unit. 

[E_DOVFLO] Raw outbound data has overflowed internal queue. 

[EjCTRLIO] Communication with controller is terminated abnormally; ses- 
sion powered off. See below. 

[E_TTY] Error in controlling terminal device (LUV_DSP or LUVJTRC 

modes only, see xlulopen). See below. 

[400+] Program check (see Appendix B). 

[500+] Communication check (see Appendix C). 

If the call fails with an E CTRLIO or E_TTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. This does not 
indicate that the call has failed for the input session. The results of this call 
can be determined by use of an xlu2info{2) call for the input *lu_chan. 
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DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 
is returned and errapi is set to indicate the error. 
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NAME 

xlu2seek — position the cursor to a field in screen buffer for LUD_3270 logical 
unit 

SYNOPSIS 

#include <xlu2io.h> 

int xlu2seek(lu_chan, foffset, ptrname) 
unsigned char *lujchan; 
long foffset, ptrname; 

DESCRIPTION 

xluZseek positions the cursor to the beginning of a field, in the screen buffer of 
the LUD_3270 logical unit (LU) specified by *luj:hati, the value returned by an 
x/u2open(3X) call. 

Depending on the value of the access mode [LUAMOD, see xlu2ctl{,3X)\ for 
this LU, xluZseek may reference protected fields, unprotected fields, or both. 
For an unformatted screen buffer, the entire space is considered one field and 
the foffset parameter unit is a screen buffer location. For a formatted screen 
buffer, the foffset parameter unit is a screen buffer field. Buffer formatting is 
indicated by the value of c Jrm in the XLU2IBUF structure for this LU, 
retrieved by an xlu2info{3X) call. 

A positive foffset indicates forward movement. A negative value indicates 
backward movement, foffset reflects the field offset from ptrname. The values 
for ptrname are: 

0 position from the start of screen buffer 

1 position from the current position in screen buffer 

2 position from the end of screen buffer 

xluZseek does not allow the cursor to wrap freely from the end of the screen 
buffer (the lower right-hand corner) to the beginning (the upper left-hand 
corner). The movement of the cursor through the screen buffer is effected by 
the value of foffset as follows: 

• If foffset is zero, the cursor is positioned at the beginning of the current 
field, which is the first non-attribute character following the first attribute 
character at, or preceding, the current cursor position. If a screen back 
wrap occurs while searching for the preceding attribute, no error is gen- 
erated, providing an attribute character is contained at the end of the 
screen buffer. Otherwise, an error condition exists. For an error, the 
current cursor position is invalid and must be reset to the location the 
user prefers. 

• If foffset is greater than zero, the cursor skips over the number of non- 
consecutive attributes, not counting the starting location. A set of con- 
secutive attributes is the equivalent of one attribute preceded and fol- 
lowed by non-attribute characters. A screen wrap results in an error con- 
dition. The current cursor position is invalid and must be reset to the 
location the user prefers. 
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• If foffset is less than zero, the cursor skips over the number of non- 
consecutive attributes. If the starting location is an attribute character, it 
is counted as one skip. A set of consecutive attributes is the equivalent of 
one attribute preceded and followed by non-attribute characters. If a 
screen back wrap occurs when foffset is less than zero, no error is gen- 
erated, as long as an attribute character, which exhausts foffset, is found at 
the end of the screen bu£fer. Otherwise, an error condition exists. For an 
error, the current cursor position is invalid and must be reset to the loca- 
tion the user prefers. 

xlulseek will fail if any of the following are true, with errapi set as shown: 



[E_ARG1] 


Invalid *lu_chan parameter. 


[E_ARG3] 


Invalid ptmame. 


[E INIT] 


API initialization not performed \xlu2init(3\) not called]. 


[E_CNTX] 


*lu_chan does not exist. 


[E_DMODE] 


*lu_chan is in LUD_RAW or LUDJTRAW mode. 


[E_BUSY] 


Busy logical unit. 


[E_OFFB] 


Cursor is beyond the screen buffer boundary. 


[OPI_WHAT] 


Invalid operation. 


[OPI_FUNCT] 


Invalid operation. 


[E_CTRLIO] 


Communication with controller is terminated abnormally; ses- 




sion powered off (see below). 


[E_TTY] 


Error in controlling terminal device (LUV_DSP and LUVJTRC 




modes only, see xlulopen). See below. 


[400+] 


Program Check (see Appendix B). 


[500+] 


Communication Check (see Appendix C). 



If the call fails with an E_CTRLIO or E_TTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. This does not 
indicate that the call has failed for the input session. The results of this call 
can be determined by use of an xlu2info{2) call for the input *lu_chan. 

DIAGNOSTICS 

Upon successful completion, a value of 0 is returned. Otherwise, -1 is 
returned and errapi is set to indicate the error. 
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NAME 

xlu2writ — write a raw segment on the LUD_RAW/LUD_TRAW logical unit 

SYNOPSIS 

#include <xlti2io.h> 

int xlu2writ(lu_chan, segmt, sees) 
unsigned char *lujchan; 
RAWSEG "segmt; 
unsigned sees; 

DESCRIPTION 

xlulwrit performs a data block write operation on the LUD_RAW/LUD_TRAW 
mode logical xinit (LU) channel specified by *lu_chan, the value returned by an 
xlu2open{3X) call. 

The RAWSEG structure, defined in xapi.h, contains the following members: 

unsigned char «s;/* segment data */ 

long n; /* segment data size */ 

unsigned char cod;/« segment data: EBCDIC/ASCII */ 

long seq; /* segment sequence in block */ 

long blk; /* block sequence in command */ 

long cmd; /« command sequence in chain */ 

long typ; /« segment type »/ 

On call, segmt->cod must be set to either the value ASCII or EBCDIC 
(defined in xapi.h) to indicate the character set of the data in the buffer. 
EBCDIC data cannot be sent on an ASCII line. 

xlulwrit writes segmt->n data bytes from the buffer pointed to by 
segmt->s. For SNA sessions, the maximum value of segmt->n is 
writjnax (defined in xapi.h) bytes. For BSC sessions, the maximum value of 
segmt->n is writ_bsc (defined in xapi.h) bytes. These values reflect the max- 
imum block size that the physical line can handle, writjnax and writ_bsc are C 
language macros and are therefore compile-time values. At run-time on an 
SNA session, the maximum data segment size is controlled by the host when 
binding session ownership. max.siz in the XLU2IBUF structure [see 
x/M2in/o(3x)] indicates this value. 

If the application program needs to send a block of data greater than the max- 
imum block size, the user must segment the data and indicate the sequence of 
segments to xlulwrit. This is done by setting the value of the segmt->blk 
parameter as follows: 

LU_DSB data stream begins (first segment in sequence) 

LU_DSC data stream continues (middle segment in sequence) 

LU_DSE data stream ends (last segment in sequence) 

LUJDSO data stream only (only segment in sequence) 

If segmt->blk indicates this is the first or only data block in the sequence, 
the controller is asked for permission to transmit. If permission is denied, the 
call will fail with errapi set to OPI_FUNCT or 480. If permission is granted or 
not needed (i.e., segmt->blk indicates middle or last), the data in the 
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buffer, at segmt->s, is written to the controller. 

segmt->blk must have continuity over consecutive xlulwrit calls, so that 
the following sequence of xlulwrit calls will result in an error return from the 
final call: 

An xlulwrit, with segmt->blk first/middle is successful and is fol- 
lowed by xlulwrit, with s e gmt - > b 1 k first/only. 

An xlulwrit, with segmt->blk last/only, is successful and is followed 
by xlulwrit, segmt->blk last/middle. 

If the host is sending data to the LU when xlulwrit is attempted, the call will 

fail with errapi set to E_DREJ. 

On success, xlulwrit returns the size of the data buffer actually written in 
segint->n. 

The calling program is blocked until the data block is written to, and accepted 
by, the controller or until sees seconds have elapsed, sees is the maximum 
number of seconds xlulwrit will wait for the write to complete. If the call 
does not complete before sees number of seconds have elapsed, the call will 
fail with errapi set to E_INTR. If the call completes before sees seconds have 
elapsed, xlulwrit will return normally with the appropriate return code. A 
sees value of 0 indicates no timing should be performed. 

xlulwrit will fail if any of the following are true, with errapi set as shown: 

[E_ARG1] Invalid *lu_chan parameter. 

[E_ARG2] segmt is the null pointer. 

[EJNIT] API initialization not performed [xlulinit{3X) not called]. 

[E_CNTX] *lu_ehan does not exist. 

[E_DMODE] *lu_ehan is in LUD_3270 mode. 

[E_BUSY] Busy logical unit. 

[OPI_FUNCT] Invalid operation. 

[E_DSEQ] Sequencing error: invalid segmt->blk. 

[E_DSIZ] Data segment too long. 

[E_DCOD] EBCDIC data cannot be sent on ASCII line. 

[EJDREJ] User may not send data at this time. 

[EJDOVFLO] Raw outbound data has overflowed internal queue. 

[EJENTR] sees is non-zero and the function did not complete in sees 

seconds or this call was blocking and an xlulintr{ZX) was 
issued (see below). 

[EjCTRLIO] Communication with controller is terminated abnormally; ses- 
sion powered off (see below). 

[EJTTY] Error in controlling terminal device (LUVJTRC only, see 

xlulopeti). See below. 
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[400+] 
[500+] 



Program check (see Appendix B). 
Communication check (see Appendix C). 



If the call fails with an E CTRLIO or E_TTY error, the error may have 
occurred on another session. In this case, the returned value of *lu_chan may 
be set to that session and will be different than the input value. This does not 
indicate that the call has failed for the input session. The results of this call 
can be determined by use of an xlu2info{2) call for the input *luj:han. 



Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 
is returned and errapi is set to indicate the error. 



DIAGNOSTICS 
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This example illustrates a C language application program that records 
keystrokes sent to a session by a terminal operator using the h_startkey 
HLLAPI function call. 

The h_startkey function call requires that you give explicit control of 
the session to the terminal user. You can do this by specifying the CON- 
PHYS option with the hjsetparms function call, and by calling the 
hjconnect function call after issuing the h_startkey call. 




#incaude "xhUapi.h" 



#dlefine LEU 1024 

nain(argc, azgv) 
int axgc; 
char «axgv[]; 
{ 

int func, ret, leng; 
char data[256] ; 

get_key key; 
char *nQlloc( ) ; 

clim(H_SETPAI^, "oanpliys"); 

func s H.STARIKEX'; 
stroike.sk_psicl = 't'; 
strdke . sk_option = SK_AIiL; 
strolkB.sk_ba££er = nalIcx;(LEN) ; 
leng = 

hllapi(&func, Sistrdke, &leng, Sret); 
cliia(H_O0NtJE3CT, "t"); 
key.^jpsid = 't'; 

Minle (clim(H_GEnKEY, Skey) 1= HE.NOKEZS) { 

parintf("5fc XsO, key.gk_optian, key.gk_buffer) ; 

} 

} 
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int func; 
char «data; 
{ 

int ret, leng; 



leng = strlen(clata) ; 
hllapK&func, data, &leng, &ret); 



retuxn(ret) ; 
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This example illustrates a C language application program that allows a 
user to do file transfers from the command line. The executable should be 
built with the name receive, and an ln(l) command should be used to give 
the executable another name called send. The program interrogates which 
way it was invoked to determine the direction of the file transfer. The rest 
of the parameters are the same as for the H_SEND and HJRECEIVE com- 
mands. 



NOTE 



Since the parameters are given on the command line, certain characters 
will need to be escaped from the shell, like the colon after the presen- 
tation space short name. This can be accomplished by enclosing the 
particular command line parameter in double quotes. For example: 
send xhllapLc "t:xfer.text(hllapi)" ASCII CRLF 



The program first goes to terminal emulation mode allowing the user to 
log on. When the host session is at the environment ready message, the 
user may exit the session (with <ESC> f d ) and the file transfer will start. 
The ready message for TSO is "READY" and for CMS is "R;". Afterwards, 
the program places the user back in terminal emulation mode to log out of 
the host session. When the user exits the host session again, the program 
terminates. 
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#ixiclude <stdio.h> 
#inclui3e "schllapi.h" 

mainCargc, argv) 
int axgc; 
char *cu?gv[]; 
{ 



ink func, ret, leng; 
dhar clata[256] ; 
int i; 

cliin(H_SE:rPARMS, "oar^Ays" ) ; 
cliin(H_OCNNECT, argv[2]); 
data[0] = 0; 

for (i = 1; i< argc, i++) { 
strcatCdata, argv[i]); 
strcat(data, " "); 
} 

cldin{»argv[0] == 'r' ? H.RBCV : H_SBND, data); 
cl±n(H_CXXlNEC7r, argv[2]); 



int ret, leng; 

leng = strlen(data) ; 
hllapK&func, data, &leng, Sret); 

retum(ret) ; 



} 



cliin(func, data) 
int func; 
char «data; 
{ 



} 
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AT&T 3270 Emulator+ HLLAPI Functions 



The following is a list of the AT&T 3270 Emulator+ HLLAPI supported 
functions: 

IBM 3270 PC AT&T 3270 

HLLAPI Emulators- 
Function Symbolic 
Number Name Name 



1 


Connect Presentation Space 


H_CONNECT 


2 


Disconnect Presenation Space 


H DISC 


3 


Send Key 


H_SENDKEY 


4 


Wait 


H WAIT 


5 


Copy Presentation Space 


HjCOPY 


6 


Search Presentation Space 


H SEARCH 


7 


Query Cursor Location 


HjQCUR 


8 


Copy Presentation Space to String 


H COPYPSS 


9 


fift Session Parannptf'T'si 


H SETPARMS 


10 


Query Session 


HQSESS 


11 


Reserve 


H_RESV 


12 


Release 


H REL 


13 


Copy Operator Information Area 


H CPOIA 


14 


Query Field Attribute 


H QATTR 


15 


Copy String to Presentation Space 


H CPSTR 


16 


Work Station Control 


H_WSCRTL 


17 


Storage Manager 


HJSTMAN 


18 


Pause 


H PAUSE 


20 


Query System 


H QSYS 


21 


Reset System 


H_RESET 


22 


Query Session Status 


H QSTATUS 


23 


Start Host Notification 


H STRTHOST 


24 


Query Host Update 


H_QHOST 


25 


Stop Host Notification 


H STOPHOST 


30 


Search Field 


H SRCHFLD 


31 


Find Field Position 


H FNDPOS 


32 


Find Field Length 


H FNDLEN 


33 


Copy String to Field 


HjCPSTRF 
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IBM 3270 PC AT&T 3270 

HLLAPI Emulator+ 
Function Symbolic 

Number Name Name 



34 


Copy Field to String 


H CPFIELD 


50 


Start Keystroke Intercept 


H STARTKEY 


51 


Get Key 


H GETKEY 


52 


Post Intercept Status 


H POSTINT 


53 


Stop Keystroke Intercept 


H STOPKEY 


90 


Send File 


H SEND 


91 


Receive File 


H RECV 


92 


Invoke DOS Program 


H INVOKE 


93 


DOS Redirect 


H REDIR 


99 


Convert Position or Row Col 


H CONV 



These functions are AT&T HLLAPI extensions, and are not available in 
the IBM HLLAPI: 

AT&T 3270 
Emulators- 
Function Symbolic 
Number Name Name 



111 Change Current Presentation Space Position H_CHCUR 

112 Write a Character in Presentation Space HJYRCHAR 

113 Connect and Interact with Presentation Space HjCONNINT 
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The following IBM HLLAPI functions are not supported in the AT&T 
3270 Emulator+ HLLAPI implementation: 

IBM 3270 PC 
HLLAPI 
Function 



Number Name 



35 Define Presentation Space 

36 Switch Presentation Space 

37 Display Cursor 

38 Display Presentation Space 

39 Delete Presentation Space 
54 Get 3270 AID Key 
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The xhllapi.h File 



A HLLAPI Functions */ 



■#def ine 


TT 

n. 




1 




ll_ 




z 


#d.ef xne 


tl 

n_ 


_SENDKEY^ 


Q 




TI 

n_ 


yiALL 


/I 




u 
n_ 




3 




TT 

n._ 


_b£iAE<Ul 


O 


^'cLef ine 


TT 

ri_ 




•7 


#d.ef me 


TT 

n_ 


/•VMJVUCC 


Q 
O 


^^cLefuis 


u 
il_ 






#clefin,e 


rr 

n_ 






^^e£me 


TJ 

n_ 


_Knov 


1 1 


■#d.ef ine 


tj 

n,_ 


1)1, 'I 
_KtiLi 


1Z 


^'cLef ine 


TJ 




1 J 


#de£ine 


tJ 
tl_ 


,QAlltk 


■1/1 


^define 


TT 

n_ 


_CPSTR 


Id 


#def ine 


TJ 

n. 




lo 


^define 


TT 

n_ 




1 / 


^^efine 


TJ 

n_ 




To 


#def ine 


TJ 
Il_ 


_QSxS 


on 


{('define 


TT 

n_ 


_RESET 


z 1 


#def ine 


tJ 

II_ 


/•AgVTlAITl It-* 

J3S£/KIXJS 


oo 
ZZ 


i^efine 


u 
n_ 






i^efine 


TJ 

n,_ 




Z4 


#def ine 


TT 
Il_ 


_STOrm?ST 


ZD 


#de£ine 


H. 


_SEOIEID 


30 


#define 


H 


.ENDPOS 


31 


#define 


H 


.EMJLEN 


32 


#de£ine 


H 


.CPSTRF 


33 


#de£ine 


H 


CPFiKLD 


34 


#de£ine 


H 


.DEFPS 


35 


#de£ine 


H 


.SWTTCHPS 


36 


#de£ine 


H 


DISPCOR 


37 


#define 


H 


DISPPS 


38 


#de£ine 


H 


DELPS 


39 


#de£ine 


H 


STAFTECEY 


50 



/* Ccxmect Presentation Space ♦/ 
/* Disconnect Eresenation Space */ 
/* Send Key »/ 
/* Wait */ 

/* Copy Presentation Space */ 

/* Search PS */ 

/* Query Cursor Location */ 

/* Copy Presentation Space to String */ 

/* Set Session Parameters */ 

/* Query Session */ 

/* Reserve */ 

/* Release */ 

/* Copy Operator Information i^ea */ 

/♦ Queiy Field Attribute */ 

/* Copy String to PS */ 

/* Work Station Control */ 

/* Storage Manager */ 

/* Pause */ 

/* Query System */ 

/♦ Reset System */ 

/* Query Session Status */ 

/♦ Start Host Notification */ 

/* Query Host Update */ 

/* Stop Host Notification */ 

/* Secirch Field */ 

/* Find Field Position ♦/ 

/* Find Field Lencfth */ 

/* Copy String to Field */ 

/* Copy Field to String */ 

/* Define Presentation Space */ 

/♦ Swicth Presentation Space */ 

/* Display Cursor */ 

/* Display Presentation Space */ 

/* Delete Presentation SP^ce */ 

/* Start Keystroke Intercept */ 
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The xhllapi.h File 



#def ine H_GBIKEY 
#def ine H_POSTINT 
#def ine H_STOEKEy 
#defijie H_GE7rAID 
#def ine H_SEM) 
#defiiieH_RE3C7 
#def ine H_INVCKE 
#def ine H_REDIR 
#def ine H_C!ONV 
#def ine H_CHCUR 
#cle£ine H_WEO]AR 
#def ine H.CTNNINT 

/* Array Sizes */ 

#def ine UXGJum 8 

/* Return Codes */ 



#de£ine 


HE. 


.SUCCESS 


#define 


HE. 


.INVAL 


#define 


HE. 


.FARM 


#de£ine 


HE. 


.WSCIRL 


#define 


HE. 


.Busy 


#clefine 


HE. 


.INHBT 


#define 


HE. 


.LENGTH 


#define 


HE. 


.POS 


#define 


HE. 


.EROC 


#cle£ine 


HE. 


SYSEBR 


#define 


HE. 


.RJNCT 


#define 


HE. 


.RSRC 


#de£ine 


HE. 


.CIA 


#define 


HE. 


JPBES 


#define 


HE. 


.Bora 


#define 


HE. 


.DATA 


#de£ine 


HE. 


.NOFTRTf) 


#de£ine 


HE. 


.NQKEYS 


#define 


HE. 


UPDATE 


#define 


HE. 


.JNUM 


#define 


HE. 


_NOiNT 



51 


/* 


Get Key */ 


52 


/* 


Post Intercept Status */ 


53 


/* 


Stop Keystroke Intercept */ 


54 


/* 


Get 3270 AID Key */ 


90 


/* 


Send Hie */ 


91 


/* 


Receive File */ 


92 


/* 


Invoke DOS Program */ 


93 


/* 


DOS Redirect */ 


99 


/* 


Convert Position or Row Col */ 


111 


/* 


Change cursor Position in PS */ 


112 


/* 


Write a diaracter in PS */ 


113 


/* 


Connect Interactive */ 



0 /* Good Return */ 

1 /» Invalid PS */ 

2 /* Parameter error or Invalid Function */ 

3 WS Ctrl action heis occurred */ 

4 /» Target PS busy */ 

5 /* Function Inhibited */ 

6 /* Data Ecxar */ 

7 /* Invalid PS Position */ 

8 /* Function Procedure Error »/ 

9 /* System Eaxnr */ 

10 /* Rmction Ubavailable */ 

11 /* Resource Unavailable »/ 

21 /* Updated OIA */ 

22 /* U^xiated presentation space */ 

23 /♦ Both of the above have been updated */ 
8000 /* Only data portion has been iipdated */ 

24 /* Nb such £ield */ 

25 /♦ Requested keys are not available */ 

26 /* A host presenation space or OIA has */ 

/* been updated */ 

301 /♦ Invalid function number */ 

302 /* File not found */ 
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#clef±ne HE.^^OCESS 305 


/* 


Access denied */ 




/jt 
/* 


Xnsuf f Icient memory */ 


#define HE_ENV 310 


/♦ 


Invalid environment */ 


#ae£ixie nE_E\jRM on 


/jt 
/* 


Iiivalid format */ 


#def ine HE_PSID 9998 


/* 


Invalid presentation space */ 


#def ine HE_NOa!ER 9999 


/* 


Parameter not 'p' or 'r' */ 


/* Hardware Base */ 






#uemie nD_jz/UAx a 


/* 


^0*70 "DT* "iOnn DP VP Jt/ 

j^iKl r\« or O^/U rv> Al */ 


#define HB_3270AT 'A' 


/♦ 


3270 PC AT #/ 


imeLine no_u^u^^o«N u 




Unahle to Determine */ 


/ * Control Pcocfrain Type it/ 






#define CP_3270PC 'C 


/* 


3270 PC Control Program »/ 


/* Control Program Level */ 






#define CL_ONE '1' 


/* 


CP Level 1.22 */ 


#define CL_TWO '2' 


/* 


CP Level 2.10 */ 


A Query system data strdiig 


*/ 




typedef struct { 






char 


sy_vemura; 


/* 


HLLAPI Version Number */ 


char 


sy_leviium[2] ; 


/* 


HLLAPI Level Number */ 


char 


sy_date[6]; 


/* 


HLLAPI Date {mDDIY) */ 


char 


sy_limver; 


/* 


UM. Version */ 


char 


sy_limlev[2] ; 


/* 


LIM Level */ 


char 


sy_hiA>ase; 


/* 


Hardware Base */ 


char 


sy_cptype; 


/* 


Control Program Type */ 


char 


sy_qplevel; 


/* 


Control Program Level */ 


char 


sy_resv1 ; 


/* 


Reserved */ 


char 


sy_resv2[2] ; 


/* 


Reserved */ 


char 


sy_psid; 


/* 


Session Short Name */ 


char 


sy_ejcterr1[4]; 


/* 


Extended Error Code 1 */ 


char 


sy_exterr2[4] ; 


/* 


Esctended Error Code 2 */ 


char 


sy_resv[8] ; 


/* 


Reserved */ 



} q_system_data; 
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/* Session Types */ 



#def ine ST_HOST 
#clef ine ST_NOTE 
#def ine ST_PC 
#define ST_DPr 
#def ine ST OTP 



/* Host Session ♦/ 

/* Notepad Session */ 

/* PC and Alternate Sessions */ 

/* DET Mode */ 

/* Cut Mode */ 



A Query Sessions data string «/ 



typedef struct { 

char qe_psid; 

ciiar qe_lname[LCNG_NAME] ; 

char qe_stype; 

short qe_size; 
} q_sessions_data; 



A Presentation S^pace Id's */ 



/* Short name of session */ 
/* Long name of session */ 
/* Session Type */ 
A PS Size */ 



#definePS_a]RR ' ' 

#def ine PS_CURR2 0x0 
#define PS_PCRUN 
#E3efine PS WSCTRL 



A Currently connected PS */ 
A Same*/ 

A PC session AP running in */ 
A WS Control session */ 



A Session Characteristics */ 



#define SC_EAB0x80 
ji^ine SC PSS0x40 



A Extended attribute bytes */ 

A Progranable symbols supported *i 



A Query Session Status data string */ 
typedef struct { 



char qt_psid; 


A 


Short name */ 


char qt_lname[LONS_NAME] ; 


A 


Laog name */ 


char qt_stype; 


A 


Session type */ 


char qt_schars; 


A 


Session Characteristics */ 


short qt_rows; 


A 


Rows in presentation space */ 


short qt_ools; 


A 


Coliimns in PS «/ 
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The xhllapLh File 

char qt_pifstat[2]; 
char qt_reserved; 
} q_status_clata; 

typedef unsigned char nnhar; 

/* C3oFy OIA data string */ 

tj^pedef stnact { 

char cp_fonnat; 
char cp_iinage[80]; 

/* OIA Iiidicatar Group */ 



/* Group 1: On-line and screen ownership */ 



MefineSETDP 


0x80 


/* Setup mode */ 


#def ine TEST 


0x40 


A Test mode */ 


#def ine SSCFONN 


0x20 


/* SSCP-LU session owns screen */ 


#def ine LCXMI 


0x10 


/* UCJ-LU session owns screen */ 


#de£ine UNCMN 


0x08 


/* Online and iK)t owned */ 


#c3e£ine BEAEY 


0x04 


/* Subsystem ready */ 


nchar group_ 


.1; 




/* Group 2: Character 


selection */ 


#de£ine EXTEND 


0x80; 


/* Extended Select */ 


#def ine APL 


0x40; 




#de£ine KAMA 


0x20; 




#de£ine AIiPHA 


0x10; 




#de£ine TEXT 


0x08; 





uchar group_2; 



/* Group 3: Shift state */ 

#de£ine NUMERIC 0x80; /♦ Numeric Shi£t */ 

#de£iiie SHIFT 0x40; A Upper Shi£t «/ 

uchar group_3; 



/* PIF Status */ 
/* Reserved */ 



A OIA Format byte */ 
A OIA Image Group */ 
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/* Group 4: PSS group 1 */ 

/* Grougj 5: Highlight group 1 ♦/ 

/* Groi^j 6; Color grxxp 1 ♦/ 



#define SEEjEICT 
#clef ine INBffilKET 



0x80; 
0x40; 



/* Operatior Selectable */ 
/* Field Inherit */ 



udhar groi:qp_4; 
uchar group_5; 
uchar groi:5)_6; 

/* Group 7: Insert */ 

#defiiie INSERT 0x80; /* Insert node */ 
\icihar group J7; 

/* Group 8: Input diihibited */ 



/* Group 8: B3rte 1 */ 






#defineCHE)CX 


0x80; 


A 


Non-resettable macMne chedk */ 


#def ine KEY 


0x40; 


/♦ 


Reserved for security key */ 


^define MACHINE 


0x20; 


/* 


Machine Chedc */ 


#def ine Ccm 


0x10; 


/* 


Camunications Check */ 


jl^def ine FBSOCSm. 


0x08; 


/* 


Program checik */ 


#def ine RETIRZ 


0x04; 






#de£ine mOBSJIG 


0x02; 


/* 


Device not wjrking */ 


#def ine VBUSY 


0x01; 


/♦ 


Device vecy busy */ 



/* Group 8: Eyte 2 */ 




#def ine BUSY 


0x80- 


/* 


Terminal busy */ 


#def ine WAIT 


0x40 


/♦ 


Terminal wait */ 


#def ine SYMBOL 


0x20 


/* 


Minus symbol */ 


#def ine FUNCTION 


0x10 


/* 


Minus function */ 


#de£ine TOGMLFCH 


0x08 


/* 


Too much entered */ 


#de£ine NENDUGH 


0x04 


/* 


Not enoogrh entered */ 


#def ine motG 


0x02 


/* 


Wrong nurtiber ♦/ 


#de£ine NUMBER 


0x01 


, /* 


Numeric field */ 
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/* GcToup 8: 


Byte 3 ♦/ 






#aef ine UNAUTH 


0x40; 


/* 


Operator xmauthorized */ 






/* 


upexoujir unauxoiuLxzcQi uuJius Euiiuciuii 


#def ine IDEAD 


0x10; 


/» 


Invalid dead "key ocxnbination */ 


#def ine WPLACE 


0x08; 


/* 


Wromg placed */ 


/* Group 8: 


Byte 4 */ 






#aeriXxe JrCiNUJJNRjr 


uxou; 


/* 


Messaj9'e penduicf */ 


#def ine PAEOTITICN 


0x40; 


/♦ 


Partiticn wait */ 






/* 




#de£iiie MISMAOXn 


0x10; 


/* 


HardMare mismatch */ 


#de£ine NOGNFIG 


0x08; 


/* 


LU zx>t ocnfigured at control imit «/ 


/* Group 8: 


Byte 5 */ 






#def ine AUTQKEr 


0x80; 


/* 


Autokey inhibit */ 


#define INFITT 


0x40; 


/* 


^^lication program has qperator */ 



/* input inhibited */ 

ucJiar group_8[5] ; 

/» Group 9: PSS Group 2 */ 

/* Group 10: Highlight Group 2 */ 

/* Group 11: Color Group 2 */ 

#def ine SELECT 0x80; /* Selected */ 

#de£iiie DISABLE 0x40; A Display disabled (Group 9 only) */ 

uchar group_9; 
uchar group_10; 
uchar group_11; 

/* Group 12: Ccnnunications error reminder */ 

#de£ine EBEOR 0x80; /* Gcranunications error */ 

#define MONITOR 0x40; /* Response time monitor «■/ 

uchar group_12; 
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/* Group 13: Printer statxis */ 



#def ine CUSTOM 


0x80 


^define MALFUNC 


0x40 


#def ine ERINnNS 


0x20 


#de£ine ASSIQST 


0x10 


#def ine WEIAT 


0x08 


#clef ine EEONTER 


0x04 



/* Printer cxxie not custoDnized */ 
/* Printer inalfunc±ion ♦/ 
/* Printer printing */ 
/« Assign printer */ 
/* What po^inter */ 
A Printer assignment «/ 
iichar groi:?>_13; 

/* Qroip 14 & 15: Reserved */ 

uchar groiq>_14; 
nchar groi:p_15; 

/* Groip 16: Aatoikiey play/reoord status */ 

#de£ine PLA7 0x80; 
j(ide£ine PEOGRD 0x40; 
nchar group_16; 

/* Group 17: Autoikey abort/paiise state */ 

#de£ineOVEREI£W OxSO; A Recording overflow */ 

#define PAUSE 0x40; 
nrihar groi55_17; 

A Group 18: Enlarge state «/ 

#de£ine ENLARGE 0x80; /* Window is enlarged */ 

iichar grou5>_18; 
} cpoia; 



#define HN_ERES 'P' 

#define HN_OIA 'O' 

#define HN.BOOH 'B' 

#def ine HN DATA 'D' 



/* Notify if updated presentation space */ 
/* Notify if updated operator info area */ 
/* Both of the above */ 

/* Notify only if data and not attributes */ 
/* have been updated */ 
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typedef struct { 

cihar hn_psid; 

char hn_type; 

char *hn_buffer; 
} host_notify; 

AThese structures rnust be used ty program sendijig strings to WS_CraL. */ 

/***************«********«*«*******»****************^ 

#de£ine CMDSIZ 2 

#def±ne NAMES 20 

struct ca_data_type 

{ 

dhar ws_and[CMDSIZ] ; 
ciiar ws_eqa; 
char ca_scm; 
char ca_psid; 
} ; /* data from CHAN3E ACTIVE */ 

struct cb_data_type 
{ 

char ws_a[id[CMD5IZ] ; 
char ws_equ; 
char cb_psid; 
short cb_srcbeg; 
short cb_srcend; 
char cb_tpsid; 
short cb_tbeg; 
} ; /* data from CXffiY BLOCK */ 

struct rd_data_type 
{ 

char vfs_C3nd[CMDSIZ] ; 
ciiar ws_equ; 
char rd_scxn; 
} ; /* data from SCREEN */ 



/* Presentation Space ID */ 
/* l]|xlate type */ 
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struct cpi_data_type 
{ 

char w5_aDad[Q4D6IZ] ; 
char ws_eqii; 
char qa_scm; 
char qa_psid; 
} ; A data from GfUERY ACTIVE */ 



struct qc_data_type 
{ 

char ws_citid[CMDSIZ] ; 
char ws_equ; 
char qc_scm; 
char qc_fill; 
char qc_code; 
} ; /« data from GXMQ?' OQLOR «/ 



struct qe data type 
{ 

char ws_citid[CMDSIZ] ; 
char ws_equ; 
char qe_fill[2]; 
short qe_oode; 
} ; /* data from GXJEEIZ EMLABGE */ 



struct qw_data_type 
{ 

char ws_cnid[CMDSIZ] ; 

char ws_equ; 

char qw_scni; 

char qw_psid; 

shoort qw_rows; /* number of rows in vdndow */ 

short qw_ools; A number of ools. in window */ 

short qw_rpos; /* row position, i:53per left comer */ 

short qw_cpos; /* col position, i^iper left comer */ 

short qw_woolor; /* window color code »/ 

short qw_boolor; A border color code */ 

short qw_flags; /* control flags */ 

short qwjpsrow; /* row on FS of xspgesc left comer */ 

short qw_pscol; /* ool on FS of xcppsr left comer */ 
} ; /* data from GHEEOf WINDCW */ 
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struct qii_data_type 
{ 

char ws.ondCGMDSIZ] ; 
char V7s_equ; 
char cpi_scm; 
char cpi_psicl; 
char qn_iiames [NAMES ] ; 
} ; A data from QUERY NAMES */ 



#define SK_AID 'D' 
#def ine SK ALL 'L' 



/* Aid keystrokes */ 
A All Keystrokes */ 



typedef struct { 

char skjpsid; 

char sk_option; 

char *sk_buffer; 
} startjceystroke; 



A Presentation Space ID */ 
A Option Code */ 



#def ine (K_ASCII 'A' 
#def ine GKJwm 'M' 
#define GK_SHIFT 'S' 

typedef struct { 

char gk_psid; 
char gk_optian; 
char gk_buf f er[4] ; 

} get_feey; 



A ASCII characeter returned */ 

A Mnencoiic ♦/ 

A Special shift */ 



A Presentation Space ID ♦/ 
A Option code character */ 



#define PI_AGCEPT 'A' 
#aef ine EE REJECT 'R' 



typedef struct { 

char pi_p5id; 

char pi_optian; 
} post_iiitercept; 



A Presentation Space ID */ 
A Option code */ 
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\ 
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File Transfer Messages 

This appendix lists the file transfer messages in numerical order and 
describes them. The message number and text appear in bold type, fol- 
lowed by an explanation and user response. 

INDFTOOl File transfer command being processed 

This message appears when the file transfer command is 
entered and the system begins processing. 



User response: none; wait for message INDFT002 to 
appear. 

INDFT002 Number of bytes of file transferred so far: » < xxxxxxx 

This message lets you know how many bytes of the file have 
been transferred to or from the host. The number is 
updated as the file is transferred. 

User response: none; wait for message INDFT003 to 
appear. 

INDFT003 File transfer complete 

The file transfer was successful. 

User response: none. 
INDFT004 File transfer complete with records segmented 

The file transfer was complete, but records greater than the 
set logical record length of the file appended will divide 
and become multiple records. 

User response: none. 
INDFT005 Filespec incorrect: file transfer canceled 

you entered some part of the filespec incorrectly, e.g., the 
path or filename. 

User response: compare the filespec in the file transfer 
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command, which will still be visible in the session, with the 
filespec requirements for your system. If it is correct, it is 
possible that the file does not exist. 

INDFT006 Command incomplete: File transfer canceled 

The user did not enter any parameters after Send or Receive. 

User response: check the Send and Receive command 
requirements and retry. 

INDFTOlO Host has not responded with timeout period: Refer to 
reference manual for more information 

The host has not responded to the file transfer within 
several seconds. 

User response: if the host session screen shows HOLDING, 
you can start file transfer by switching to the host session 
and pressing PA2 (in TSO). If X SYSTEM or X appears in 
the host session screen operator information, wait for it to 
clear. These specify that the system is working slowly. If 
you want to stop file transfer after several time-out messages 
appear, switch to the host session, press Reset to clear the 
operator information area, and press PF2 to stop the file 
transfer, or CLEAR to continue This state can be caused by 
line problems. If IND$FILE is not installed at the host, jump 
to the application program session and press Crtl+Break to 
stop the file transfer. 
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API Program Check Error Codes 



This appendix lists the values of errapi that can be returned when API 
system calls fail because of errors in the data received from the host. 



Value Explanation 

401 unknown data stream command 

402 invalid buffer address in data stream 

403 data follows 1-byte commands in data stream 

404 data stream ends in order-pending state 

405 invalid source device on copy command, or source device 
buffer locked on copy command, or source and 
destination device incompatibility on copy command 

406 ESC character missing in second position of command sequence 
411 Request/Response Unit (RU) too long (LU.Tl) 

413 fimction not supported 

420 exception response request received when definite 
response only specified by BIND 

421 definite-response request received when exception 
response only specified by BIND 

422 NO response not allowed 

423 format indicator not allowed 

430 sequence number error 

431 chaining error 

432 bracket error 

433 data traffic inactive 

434 direction error 

443 read command must have Change Direction but not End Bracket 

445 Activate Logical Unit (ACTLU) request is for neither 
cold activation nor Error Recovery Procedure (ERP) 

450 BIND profile error 

451 BIND primary protocol error 

452 BIND secondary protocol error 

453 BIND common protocol error 

454 BIND screen size error 

455 BIND LU profile error 

456 BIND LUX error 

457 BIND cryptography specified 

462 data stream error detected by LU.Tl 

470 unknown data byte X'OO' - X'3F' or X'FF' 
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Value 


Explanation 


480 


user request lost due to host SELECT (BSC) or arrival 




of message from controller 


toi. 


user request losi aue to nose 9cl>cv.x wiin pau couimana vi's^ oniy^ 


482 


host SELECT received with response to user request (BSC only) 


483 


host SELECT with bad command received with response to user request 




(BSC only) 


490 


buffer not available for write command 


498 


negative response received 


499 


exception request received 



For additional information, see the IBM publication IBM 3270 Information 
Display System, 3274 Control Unit Description and Programmer's Guide, GA23- 
0061. 
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API Communication Checic Error Codes 



This appendix lists the values of errapi that can be returned when API sys- 
tem calls fail because of conditions detected at the local communications 



interface. 




Value 


Explanation 


501 


Data Set Ready (DSR) lost 


502 


Clear To send (CTS) lost 


504 


Normal Disconnect Mode (NDM) 


505 


NDM 


510 


Physical Unit (PU) is not active (this is SNA condition) 


518 


segmentation error (internal Deactivate Physical Unit 




(DACTPU)) (this is an SNA condition) 


519 


received frame too long 


520 


timeout (no frames) 


521 


timeout (no flags) 


525 


20 Exchange Identification (XID) commands received in a row 


528 


Frame Reject Response (FRMR) sent; Frame Reject Mode 




(FRM) entered (internal DACTPU) 


529 


modem acting up (internal DACTPU) 


530 


clocking or CTS lost (internal DACTPU) 


531 


received STX....ENQ (BSC only) 


532 


idle timeout 


534 


protocol timeout 


593 


received EOT instead of ACK (BSC only) 


594 


received RVl to ETB block (BSC only) 


595 


lost CD while receiving (BSC only) 



For additional information, see the IBM publication IBM 3270 Information 
Display System, 3274 Control Unit Description and Programmer's Guide, GA23- 
0061. 
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API User/System Error Codes 



This lists the values of errapi that can be returned when an API syste 
call fails because of user application or system errors. 



Error Message 


Explanation /Possible Cause 


1 


OPI NUM 


Non-numeric data entered in numeric field 


2 


OPI_SYS 


The keybord has been disabled by the host 


3 


OPI~WHAT 


Invalid operation 


4 


OPI FUNCT 


Invalid operation 


5 


OPI_ELSE 


Improperly positioned cursor 


6 


OPIjrOOM 


A field overflow has occurred 


7 


OPT BAD 


Bad key translation 


201 


E ARGl 


sc_ifil is the null pointer 






invalid lujchan parameter 


202 


E ARG2 


ky_ifil is the null pointer 






invalid func parameter 






invalid request 






s is the null pointer 






segmt is the null pointer 


203 


E_ARG3 


invalid lujport parameter 






iiivcuia (ug 






invalid ptrname 






n ic fliA mill noinfpT" 






the value at n is less than 1 


204 


E_ARG4 


invalid ludmod parameter 






invalid parameter 






retcod is NULL (LUEVENT with KYjCTRL 






only) 


205 


E_ARG5 


invalid luvmod Darameter 


206 


eIoffb 


cursor is off the screen buffer boundaiy 


207 


E KCTL 


error in keyboard control file 


208 


E SCTL 


error in screen control file 


209 


E_RSRC 


controller has insufficient resources 


210 


E_BNDREJ 


host mismatch, bind rejected 


211 


E TRMBSY 


SNA/BSC terminal is busy 


212 


E HOSTID 


illegal SNA/BSC host identification 


213 


eIctrlio 


communication controller problem 


214 


EJTTY 


terminal device control problem 


215 


POW OFF 


te3278 emulator terminated 
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API User/System Error Codes 



Error Message 

216 E_ACCS 

217 E_CNTX 

218 E_BUSY 

219 EJNIT 

220 E SESLIM 

221 E_DMODE 



222 E_DSIZ 

223 E_DSEQ 

224 E_DREJ 

225 EJLSIZE 

226 E_MODL 

227 E_LINID 

228 E_CNTID 

229 E_DOVFLO 

230 E_PATH 



231 


E. 


RTMG 


232 


E. 


_XLIB 


234 


E 


NASCII 


235 


E. 


PCOD 


236 


e" 


_XPRNT 


237 


E. 


.INTR 


238 


e" 


ICOND 


239 


E 


secur 



Explanation/Possible Cause 

access mode violation 

*lu_chan does not exist 

BUSY state mismatch on API call 

API initialization not performed 

number of sessions exceeds limit 

lu is in LUD_3270 mode 

lu is in LUDJRAW mode 

lu is in LUD_RAW mode or could not enter 

requested data transfer mode 

data segment too long 

sequencing error - invalid segmt->blk 

controller does not acknowledge data 

size mismatch between bind and device (bind 

command is legal) 

physical terminal (as described by scjfil) 

cannot support model number 

illegal line identification 

illegal controller identification 

raw data buffer overflow 

pu_name is the null pointer 

invalid name parameter 

error in opening runtime message file 

excluded library function 

lu on ASCII line but ses is non-ASCII 

LUDJTRAW is unavailable on ASCII line 

request for transparency rejected 

primitive aborted by interrupt 

invahd inhibit condition (LURSET) 

invalid security mode request 
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API LUV_TRC Mode Status Line 

Displays h-i 
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API LUV_TRC Mode Status Line Displays 

An API trace display is output in the status line. Each trace line is of 
the general form: 

xlu2... nl misc_params lu: n2 err: n3 

where: 

xlu2. . . is the name of the API function 

nl is the^one digit numerical field containing the called value of 

lu_chan (except for xlu2open, see below). 

miscjjarams are miscellaneous parameters displayed for this call, as 
described below 

n2 is the one digit numerical field containing the returned value 

of lu_chan 

ti3 is the three digit numerical field containing the value of the 

error code 

Trace output, particularly the miscjjarams fields, for each API call trace 
are described here. The manual pages shotdd be referenced for each 
description. 

xlu2qpen pujiame np ludmod luvmod lu: nl err: nS 

where: 

pujtame controller process (in place of nl; only the returned value of 
lu_chan, n3, is used) 

np is the three digit field containing the value of lujport 

ludmod is the one digit field value of ludmod (see xapi.h) 

luvmod is the one digit field value of luvmod (see xapi.h) 



xlu2clos lu: n2 err: n3 

has no miscjjarams field entries 
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xlii2func nl LU. ... lu: n2 err: n3 

where: 

LU. . . . is the func followed by name: LUPRND, LUPRNF followed by 
the file name, LUPRNC followed by the command string, or 
LURSET followed by the Reset-Inhibit-condition mode 



xlii2ctJ. nl LU. ... na pos: np col: nc Idn: nl lu: n2 err: n3 

where: 

LU. . . . is the request: LUDTIM, LUEVENT, LUEVIMED, LUDMOD, 
LUVMOD or LUAMOD 

na is the three digit field value of arg (see xapi.h) 

np is the four digit field value of the current cursor position rela- 
tive to the start of the buffer 

nc is the three digit field value of the current cursor column 

nl is the two digit field value of the current cursor line 

xlu2seek nl foffset: nf ptxname: nn pos: np ool: nc lin: nl lu: n2 err: n3 
where: 

nf is the four digit field value of foffset 

nn is the one digit field value of ptrname: 

and all other fields are as in 3clu2ctl. 

xlu2gets nl req: nr ret: ssss nt pos: np ool: nc lin: nl lu: nl err: n3 
where: 

nr is the four digit field value of the buffer length 
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ssss is the initial five characters of the returned string 
nt is the four digit field value of the returned string length 

and all other fields are as in xlu2c±l. 



xlu2puts nl string ret: nt pos: np ool: nc lin: nl lu: n2 err: n3 

where: 

string is the initial four characters of the returned string 
nt is the four digit field value of the transferred string length 

and all other fields are as in xlu2ctl. 



xlu2wrlt nl nr seq: ns ret: nt lin: nd lu: n2 err: n3 

where: 

nr is the four digit field value of the data buffer length (segmt->n) 

ns is the four digit field hex value of the data block sequence 

(segrat->blk) 

nt is the four digit field value of the written data length (segrat- 

>n) 



xlu2read nl req: nr ret: nt siz: nz seq: ns lu: n2 err: n3 

where: 

nr is the four digit field value of the requested buffer length 

(segrat->n) 

nt is the one digit field value of segrat->typ 

nz is the four digit field value of the size of the returned data 

(segrat->n) 

ns is the four digit field hex value of the relative position of the 

data block (segint->blk) 
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API External Symbols 



This appendix lists the global symbols used by the API library. Applica- 
tion programs may not define these symbols externally. 



ACtVDi 


ACtvqe 


AEvtad 


AEvtst 


Arljacs 


A "DT ^1 

ArljCiS 


Al l_Ctl 


Al l_ClDg 


Al 1 get 


Al l_lUpu 


API_opn 


API_pos 


Ai l_pUt 


Ari_ret 


AJri_seK 


A Xi'^AAf 
FiXasXXXl 


Al call 


Al test 


APutae 


oAKtab 


oEgnnd 


DUidbg 


oUiiup 


CAliZZ 


l-rla._atr 


u r_it 


L,ur_rt 


\wVtaze 


DIscae 


DIscqe 


Dbazc 


Ubcza 


DScvtc 


ubeza 


DSeau 


Ubersg 


DSeua 


Ubia 




LIblSDt 


L/bluD 


i^bovra 


DSpcrt 


DSptab 


DSptat 


Ubrdmi 


Ubrdzz 


Ubread 


DSrta 


Dbsba 


DSscsr 


DSscsw 


Dbtui3 


DSvscs 


DSwini 


DSwrit 


bNdnnd 


bloa 


FIxaev 


CT A 1 

rLaljDK 


rijratt 


r w atao 




HExdump 


HTT TTT7 
rllLll£i 


iiNit exit 


11 


11 


ii^^inz 


ii^par 


11 v^qul 


11 v^qUl 


IrCtcb 


IPCtdr 


IPCtki 


IrCtrace 


IrCxeq 


TTP/^ A 


KIktsk 


KYmap 


KYtask 


KYtcb 


LClpid 


MOveae 


OUtmap 


PAnic 


PLuscur 


rOoiO 


rOOlOb 


rUolUx 


rKnit 


l^UtDUI 


13T Tl^nc 

1 u tins 


^^uvtaa 


s^cvtst 


V^ropqe 


y ueuu 


REverse 


Dv-aav 


bi^DaKt 


b^-crsi 


b^aata 


3v_aown 


Q.C^AciC\\ 

dVi^cisui 


C^C^AcCO 

bV^QSUZ 


CnAcM,. 
bV^QSUO 


bv^asu4 


9v,czax 


oii^eeoi 


oL.eras 


b^nome 


bv-Key 


bv^iear 


sv^ieit 


Dv^opyi 


ov^opyo 


bv^rigt 


b^sna 


bv-tao 


bv^tasK 


Dv-upro 


Dv-uprt 


bL.vprt 


bcnaae 


brio_stat 


olgCat 


SIgign 


CT (\A 
Dl_IlCl 


bUStSK 


lASKSt 


1 JtlZbUI 


1 ri Al 1 


1 jnariai 


i XxaW 




TRrfrl 


TT-Tnira 
1 n.i. urd 




THdraw 


THecho 


THence 


THeras 


THerms 


THexec 


THflsh 


THgopp 


THgoto 


THgoxy 


THgtfg 


THgtnm 


THgtnt 


THgtst 


THinch 


THinit 


THink 


THipti 


THkeyb 


THlick 


THluiz 


THong 


THopia 


THough 


THouts 


THpipO 


THpipr 


THpipw 


THpipz 


THpnrd 


THprin 


THputs 


THrall 


THrill 


THshlx 


THsigO 


THsigl 


THsig9 


THstrm 


THtask 


THud 


THug 


THumb 


THus 


THusag 


THutrm 


THwack 


THxptx 


THzigz 


THztrm 


UFxaev 


UPdate_crt 


actvbf 


actvqe 
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aecb 


aevtad 


aevtst 


api_ctl 


api_dat 


apijdbg 


api_opn 


api_put 


apijred 


apiintr 


aptest 


aputae 


bltp 


buffup 


callzz 


ctl_prim 


curjlt 


curjrt 


detjclr 


detjerr 


det_fea 


dsalts 


dscZa 


dscvtc 


dsehlt 


dsersg 


dseua 


uSldD 


dSITll 


dsovra 


dsrdmi 


dsrdzz 


dsread 


dsscsr 


dsscsw 


dssie 


dswrit 


endnnd 


errapi 


fixaev 


udljok 


fldnam 


gldat 


glquid 


hexdump 


ipc 


ipcbfi 


ipcmz 


ipctcb 


ipctdf 


ipctki 


KlKtSK 


kymap 


kytask 


iuzcti 


lu2gets 


luZinfo 


lujexst 


movjchrs 


movjiumb 


panic 


pluscur 


poolO 


prmnam 


prn_arg 


prnit 


qevtst 


qpopqe 


quOqcb 


replay 


req_cmpl 


rset_map 


scafun 


scaget 


scapi 


scarep 


scasek 


scasnd 


sccoid 


sccrsl 


scdata 


scdsOl 


scds02 


scds03 


sceras 


scexec 


schome 


scnxte 


scopyi 


scopyo 


scsswp 


sctab 


sctask 


scvprt 


scvx 


sendae 


showbf 


sigala 


sigcat 


sustsk 


t 


taskst 


thapi 


tharaw 


tharst 


thcola 


thcolr 


thctrl 


thdraw 


thecch 


thecho 


therms 


thexec 


thexta 


thgoxy 


thgtfg 


thgtnm 


thinit 


think 


thintr 



apaddr 


apcall 


apijcls 


apijfun 


api_get 


api_iupd 


apijret 


api_sek 


api_wrt 


baktab 


begfind 


bfaval 


cfld_atr 


chk_prm 


clear_map 


cvta2e 


dbgfle 


det_att 


discae 


discqe 


dsa2c 


dseZa 


dseau 


dseclr 


dsfa 


dsfu 


dsisbt 


dspcrt 


dsptab 


dsptat 


dsrta 


dssa 


dssba 


astur3 


dsvscs 


dswini 


enjoin 


etoa 


find_attr 


foratt 


fwd_att 


fwdtab 


hexrel 


inibit 


initjexit 


ipcpdf 


ipcqdl 


ipcqui 


ipctrace 


ipcxeq 


is_att 


kytcb 


iclpia 


lu2close 


lu2open 


lu2puts 


lu2seek 


moveae 


oldjfunc 


outmap 


poolOb 


poolOx 


prjprimd 


putbtif 


putins 


qevtad 


queuO 


rawlib 


rcvjnsg 


scadat 


scadv 


scafin 


scapos 


scaput 


scared 


scawrt 


scbaKt 


scbonz 


scdims 


scdisp 


scdown 


scds04 


sce2al 


sceeof 


sclear 


scleft 


scmgst 


scrigt 


scsini 


scsna 


scupro 


scupxx 


scvg 


setjcses 


set_map 


sho_stat 


sigign 


st_ild 


sttic_if 


th2bui 


thSrng 


thVMIN 


thasav 


thasgn 


thaw 


thcura 


thdlch 


thdpsl 


theclr 


thence 


theras 


thflsh 


thgopp 


thgoto 


thgtnt 


thgtst 


thinch 


thipti 


thisgi 


thkeyb 



1-2 HLLAPI PROGRAMMER'S GUIDE 



API External Symbols 



thlick 

thong 

thpipr 

thrill 

thtask 

thztrm 

usr_01 

usr_07 

WW 

xlu2info 
xlu2seek 



thlnkO 

thopia 

thpipw 

thscld 

thud 

tinfo 

usr_02 

usr_08 

xiat 

xlu2init 
xluZwrit 



thlnkr 

though 

thpipz 

thshlx 

thug 

tsep 

usr_03 

usr_09 

xlu2clos 

xlu2intr 



thlnkw 

thouts 

thprin 

thsigO 

thutrm 

ufxaev 

usr_04 

usr_10 

xlu2ctl 

xlu2open 



thlnkz 

thpipO 

thputs 

thsigl 

thwack 

unodef 

usr_05 

vnonlib 

xlu2func 

xlu2puts 



thofhl 

thpipk 

thrall 

thstrm 

thxptx 

update_crt 

usr_06 

wPrt 

xlu2gets 

xlu2read 
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Glossary 



attention identifier (AID) key 

A non-ASCII control key (for example, clear, PF, PA, 
or Enter). 

American National Standard Code for Information Interchange (ASCII) 
One of the two standard codes used for exchanging 
information among data processing systems and 
associated equipment. 

attribute byte In 3270 applications this is the byte used for data 

security to indicate whether a certain field can be, or 
has been, updated. 

autoskip The cursor will automatically skip to the next unpro- 

tected field when it encounters a field that is both 
protected and numeric. 

combination keys Keys that must be used in conjunction with another 
key(s) to produce a specific function. These keys 
include Control and Shift. 



copy The function that allows you to mark source lines in 

one location and move them to a target location. 

current connected presentation space 

The active session to which you are connected. 

extended error code 

A data string generated by an internal system error 
that is used by the AT&T Tier 4 Support Group for 
diagnosis. 

logging on The procedure by which you provide user 

identification, and generally a password, before 
establishing communications with an AT&T 3B com- 
puter or a remote host computer. 
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Glossary 



menu 



A list of available options from which you select the 
one that you want. 



operator information area (OIA) 



The bottommost line of your screen, where you 
receive information about the status of your work 
station and the remote host computer. 



presentation space (PS) 

A region in computer storage that can be displayed 
on your terminal screen. 



source presentation space 

The presentation space from which information is 
transported using a copy function. 

target presentation space 

The presentation space in which the information is 
placed. 

terminal operator A human user of a HLLAPI application program. 

unprotected field A field that is available for the operator to use to 
enter or modify data. 



PSID 



Presentation Space Identifier; short name of the 
presentation space. 



session 



A connection between your work station and a 
remote host computer. 



short name 



The one letter name (A through 2) of a presentation 
space. 
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3270 data stream mode 1: 8; 4: 1, 9, 11 

A 

API 1: 1, 8; 4: 1-4, 6-8, 10-14 

AT&T 3270 Emulator+ HLLAPI Tutorial 1: 

7; 3: 1-2, 4, 9, 11 
attribute bytes 2: 13 

C 

C language functions 1: 1, 8 

calling parameters 2: 8-9; 3: 8 

Combination keys 2: 2 

Communications Functions 1: 7; 2: 4; 3: 2-3 

D 

data arguments 2: 8 
distributed processing 1: 3 

E 

Environment Functions 1: 7; 2: 7; 3: 3, 8 
environment variables 2: 12; 3: 11 

F 

File Transfer Functions 1: 7; 2: 5; 3: 3, 6 
function call 1: 1; 2: 5, 7-10; 3: 1 
function number 3: 3 

functions 1: 1, 5-7; 2: 3-5, 8-9; 3: 1, 3, 9; 4: 
1-2, 8, 11, 13-14 



H 

hexadecimal format 3: 4, 10 

HLLAPI 1: 1-8; 2: 1, 3-12; 3: 1-4, 8-11 

host session 1: 3-4; 2: 1 

K 

keystrokes 1: 3-7 

L 

link 2: 11-12; 4: 3, 8, 10 
Local Environment Functions 1: 7; 2: 3; 3: 
2-3,5 

logical unit 4; 1, 9, 11-12 
LU 2: 13-14; 

O 

Operator Information Area 2: 2; 4: 14 

P 

Presentation Space 1: 4-5, 7; 2: 1, 3-4, 6; 3: 
3,7 

presentation space 1: 4-6; 2: 1, 11, 13-14; 3: 
2 

R 

raw data stream mode 1: 8 
return code 2: 9-11; 3: 8 
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s 

sessions 4: 7 

Signals 4: 11 

SNA 4: 1-4, 8, 10 

Storage Manager function 2: 5 

T 

tutorial editing mode 3: 9 

U 

UNIX System 1: 7; 2: 7, 12-13; 3: 3, 9, 11 

W 

WS Ctrl 2: 1, 10 
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